Developer documentation

the development environment

Prerequisites / Download

• The project was built using Netbeans. Latest 6.8 version offers a better support for JavaFX (new composer plugin) and is recommended. Be careful to download the "All" bundle that includes both JavaFX and "Java Web and EE".
• The only J2EE application server that is currently supported is JBoss: if you do not already have a JBoss server dedicated to tests, you will need to download it from http://jboss.org/jbossas/downloads/. There is an issue with version 5.1.0, recommended version is 5.0.1.GA.
• To check out the source code, you need a SVN client. Linux: see the documentation of your distribution. On Windows: TortoiseSVN is a really nice tool.
• Source code can be downloaded from SourceForge repository. Instructions on this page.

Setting up the projects in Netbeans

There are five dependent projects. Netbeans project files are available for each project, and you should be able to open them just by choosing "Open project" and choose the corresponding directory under trunk/.

• core: the main project (EJB project) that contains core algorithms and common classes used by both the client and the server.
• web: web front-end (WAR project). Is deployed through the ear project.
• ear: the application package (EAR). Contains core and web and is meant to be deployed on a JEE application server.
• jfxext: a set of helper classes for JavaFX (to be replaced by native functions when JavaFX gets more maturity).
• fx-client: the rich JavaFX client. Depends on jfxext and core.

After loading the projects, you have to:

• Register the JBoss server using the "Tools / Servers" menu and assign this server to the ear project ("Project Properties" / "Run" -> Server). Otherwise. If no target J2EE server is associated to the project you may get many "Cannot find symbol" during compilation.
• Tune your JavaFX installation if not already done (see Hacking JavaFX 1.0 to use Java 1.6 features).
• Once the previous steps are done, you should be able to compile the three projects (in that order: the core, then jfxext and finally fx-client) by selecting "Clean and build" on each project (right-click). Note that it's normal if the two JavaFX projects (jfxext and fx-client) are still flagged with red exclamation marks (still some problems with the JavaFX module in Netbeans), the important point is that the projects can compile.
• Once these steps are done, you should not have any compilation errors any more. If so, please refer to the troubleshooting section.

Deploying the agent

Right click on the ear project and choose "Deploy". This will start the JBoss server automatically, deploy the application and you shall be able to access the server by typing http://localhost:8080/objectwiz in a browser.

Notes:

• At this step, you will not be able to use objectwiz by clicking on the "Launch" button because the client was not embedded within the WAR archive. See the corresponding section below.
• When deploying the core project for the first time, you will get a few exceptions in the console and/or the log files. The first one shall be: "objectwizDatasource not bound". These exceptions are normal, they indicate that the internal database where Objectwiz stores users' preferences was not found.

Running the client

After opening the fx-client project, you need to create the configuration files in fx-client/src. Sample configuration files are available (with the same name plus .sample):

• client.properties: defines the default agent that will be used by the client.
• fxclient.properties: defines the behavior of the FX client (automatic login, experimental mode, etc.)
• log4j.properties: configuration file for log4j (messages that will appear on the Java console).

Once these files are created, you shall be able to run the client by launching the project from Netbeans (right-click on fx-client and select "Run project"). You can also click on the green "Play" button directly once you will have set fx-client as your default project (right-click, "Set as main project").

Embedding the client into the deployable application

1. This step is required only if you want to launch Objectwiz by clicking on the "Launch" button that appears in the center of Objectwiz web splash screen. It is not a requirement if you just launch Objectwiz from within Netbeans using the "Run project" action.
2. Edit the project properties of the fx-client project and make sure that the "Self signed jar" checkbox under "Application" is checked.
3. Run the ant target called deployClientToWar. (To run an ant task, select the "build.xml" file in the "Files" window, right-click on the desired task in the "Navigator" window and select "Run target").
4. Redeploy.
5. After redeploying, you should be able to run the client using Java Webstart after clicking "Launch". If your computer is running a JavaFX program for the first time, an extra splash screen from Sun will appear.

NOTE: at this step, you shall see a login screen and any attempt to enter credentials will fail (see following section "Security").

Security and additional setup

Objectwiz client communicates with the server using HTTP. The interface is protected by default by HTTP Basic authentication and the user must have the objectwizUser role to be able to successfully authenticate.

On JBoss, the default security domain is the same as the JMX console. Passwords and roles for this domain are managed in server/<instance>/conf/props/jmx-console-XXX.properties.

For additional set up, please refer to the setup instructions for non-developpers.

You are done!

Development environment is ready now. After entering credentials on the rich client, you shall see a list of available persistence units. If you do not have any other application within the server, you will only see one unit: objectwiz (the internal unit where users' preferences are stored).

NOTE: For the moment, after deploying JPA-enabled applications, you will have to redeploy objectwiz so that they are detected and appear in the list.

Run a sample application

If you just downloaded and installed JBoss as mentioned in the first section, you have no sample application in your server and objectwiz will not be able to detect any persistence unit (~database). You will need to deploy a sample application that uses JPA persistence in order to make it discoverable by objectwiz. The dvdstore example from Seam framework is a good start: it is available in the examples/dvdstore directory of Seam releases.

Troubleshooting

I got a lot of "Cannot find symbol" errors at compile time.

It's most probably linked to a problem with the server runtime in the core project. Make sure that the correct server is selected in "Properties / Run -> 'Server' attribute".

Cannot find symbol: class Desktop (location: package java.awt).

JavaFX compiler does not support Java 1.6 out-of-the-box for the moment. A little trick is needed. See this article.

Starting Objectwiz through Java Webstart by clicking on "Launch" does not work.

Make sure that you did follow the steps described in Embedding the client in the deployable application. If you still get problems, check this guide or ask for help.

I have another JPA-enabled application in my JBoss server but it's not detected

Check the server logs for exceptions/warnings from org.objectwiz package. They may indicate the cause of the problem.

Any other problem?

Ask for support on Sourceforge.

Collaborative tools

In progress.