ObjectWiz Setup Instruction

Back to home page

Table of contents

  1. General setup instructions
    1. Download and deployment
    2. First launch
    3. Configuring authentication (required)
    4. Additionnal configuration (optional)
  2. Platform-specific instructions
    1. Deploying on JBoss
  3. Troubleshooting

1. General setup instructions

Download and deployment

You can download objectWiz from sourceforge. The package consists of a single WAR file to deploy into your favorite application server.

Currently, the only supported application server is JBoss because it is the application server we (the developers of objectWiz) use daily at work and we do not know yet what are the users' needs. However, objectWiz has been designed to support any kind of server that contains a persistence layer. Adding support for another J2EE server involves subclassing an abstract class that contains only a few methods, and here are the instructions to develop a new agent.

If there is a strong demand for a particular application server, we will consider developing the agent, please do not hesitate to fill in a request on the corresponding feature request page.

Here are the specific explanations for JBoss.

First launch

Once the WAR file is deployed, you should be able to access it in your preferred browser using an URL that depends on your application server but should look like: http://localhost:<port>/objectwiz/

On the first deployment, objectWiz will try to create the internal database that will be used for storing users' preferences, so you should see the following: (screenshot). If you encounter an error screen (screenshot), please refer to the troubleshooting section.

Click on "Click here to continue" and you should be able to see the launch page which is the entry point for launching objectWiz client. This page also lists the persistence units (i.e. the databases and their object-relational mapping) that were detected.

Hot deployment of persistence units is not supported yet. Units are detected when the application is deployed, so any persistence unit that will be registered to the application server after objectWiz is deployed will not be detected: you will need to re-deploy objectWiz.

Clicking on the "Launch" should start the JavaFX application.

Java Runtime (> 1.6) is required to launch the client.

You should end up on a login screen where no credentials will grant you access until you configure security.

Configuring authentication

Data is exchanged between the client and the server through a servlet located in the relative path /agent. If the URL for accessing objectWiz is http://<host>:<port>/objectwiz, then the URL of the servlet is: http://<host>:<port>/objectwiz/agent

The same credentials apply for accessing the servlet from your browser and from objectWiz Java client. Authentication to the servlet is delegated to the application server and requires that the user logs in using BASIC http authentication with the following role: objectwizUser. Please refer to the documentation of your application server for more information on how it handles security related to the servlet standard.

Here are the detailed steps for JBoss.

Additional configuration

SSL

We recommend that you configure your application server to serve objectWiz WAR through a SSL secure connection.

Logging

You may want to create a specific log file for objectWiz servlet.

The servlet will mainly issue log events for the following packages:

Platform-specific instructions

JBoss

Deployment

Copy objectwiz.war to the deploy directory of JBoss.

Wait a moment: the WAR application is deployed and you should be able to access it at: http://<host>:<port>/objectwiz.

Configuring default authentication

By default, objectWiz WAR application is configured to use the same security domain as the jmx-console. This choice was made because objectWiz gives access to every persistence unit that is deploying within the server and every user logged in to objectWiz will be able to perform any operation i.e. has the profile of a administrator of the JBoss server.

However, as the communication servlet requires that the user has the objectwizUser role, nobody can log in to objectWiz until they are given this role.

Therefore, to grant access to a user, please make sure that:

  1. A password is assigned to this user in JBoss conf/props/jmx-console-users.properties file.
  2. The list of roles associated to this user (separated by commas) contains objectwizUser (inconf/props/jmx-console-roles.properties).

If you want to user another security domain, you have to change the default

Use a custom security domain

If you wish to use a custom security domain, you will have to change the contents of the WEB-INF/jboss-web.xml file that is contained with the WAR file. This can be achieved with the following steps:

  1. Explode the WAR archive into a temporary directory:
    • Create a directory called objectwiz.war in a temporary directory located outside of JBoss deploy/ directory: mkdir ~/tmp/objectwiz.war
    • Change your current working directory to this directory: cd ~/tmp/objectwiz.war
    • Copy the WAR file download from sourceforge to this directory: cp <path to downloaded objectwiz.war> .
    • Unpack the contents of the WAR file using Java jar command: jar xf objectwiz.war
    • Remove original WAR file: rm objectwiz.war
    • You have now successfull exploded the WAR archive.
  2. Edit WEB-INF/jboss-web.xml: you can replace the contents of <security-domain> to the domain of your choice. The rules that will apply now depends on the contents of JBoss conf/login-config.xml. Please refer to the JBoss documentation for more information.

Troubleshooting

This section is still far from complete, if you do not find the answer to your problem here, do not hesistate to file a request on the following page.

Error screen: "objectWiz was unable to detect the appropriate agent for your environment."

This usually means that your application server it not supported. See this note.

Error screen: "The system was unable to connect to the internal persistence unit."

The internal persistence unit is the database used by objectWiz to store users' preferences and internal objects. To connect to this database, the servlet relies on the standard J2EE mechanisms. It tries to connect to the datasource called objectwizDatasource.

If this datasource does not exist, the servlet will try to create with the following steps:

  1. Check if a datasource file named objectwiz-ds.xml exists in the deployment directory of the application server.
  2. If the datasource file exists, then the servlet stops at this step. You will have to make sure that the datasource file is valid and that the information it contains is valid.
  3. If the datasource does not exist, the servlet will attempt to create it (given that it has the rights to do so) and reference a database that will be created in a sub-directory named objectwiz-database in the directory where the server stores application data.

You can check the server logs to know which step failed and figure out why the servlet failed to connect to the datasource.