Getting Started with Direct to Java Client (D2JC)

Last modified by Lazy Lazarus on 2025/03/28 11:42

This tutorial will get you started with Direct to Java Client, also known as D2JC, by simply creating a new project in WOLips and adding an EOModel, then launching it. The first few steps involve downloading and installing the D2JC WOLips Project Template. These steps shouln't be required for much longer.

Create a Project Templates directory

You need to create a "Project Templates" directory in ~/Library/Application Support/WOLips/

Download the D2JC Project Template

You can add new project templates to WOLips in addition to the built-in ones it ships with.

Go to WOLips Project Templates and download the D2JC Project Template.

Save the Project Template

Save the template .zip file in the Project Templates directory, then unzip it.

New Project from Template

Start Eclipse and Select File -> New -> Other... -> WOLips -> WOProject From Template

Select the template

Select Direct To Java Client WebStart Project from the list of Templates

Define Packages

Define the Java Packages for your project. One of the key concepts to understand with a Java Client appication is that there can be both client-side and server-side classes for each of your Entities. The incremental and Ant builders for the client-side classes specifically lookes for classes with "client" in their package name to determine if they should be part of the client-side classes, so make sure your Client-Side EOF Class Package includes "client" in it at some point.

Name your Project

Give it a name just like you would with any other WebObjects Application. Just click Finished here instead of "Next" as we will add your EOModel to the project later.

Launch the Application

Launch the Application just like any other WebObjects application.

Select the Application class

Select the Application class that is in your Base Package.

Possible problem: Can't connect to localhost/127.0.0.1

When using Mac OS X 10.15 Catalina and OpenJDK 11 you may find the WebObjects server may not be reached by the Java Client via localhost (127.0.0.1) even though accessing the WebObjects server application via web browser works well.

You will experience client network/socket exceptions like "host down" or "connection refused" when you call the client execution script via terminal.

Solve this by changing the launch parameter -WOHost to a local IP of the machine like 192.168.0.112.

Missing EOModel Error

The application will launch like a Web Client WebObjects application, but instead of opening a Web browser and displaying the contents of the Main component, A D2JC application will call the client-side launch script that will automatically launch the Clent-Side application. Since we did not add an EOModel File to our project, WebObjects can't automatically create a Swing UI based on it, so we get this error instead.

Quit the Java Client Application

You will see that the Java Client application is a regular application with it's own menu bar and default options. You can quit the Java Client application by iether selecting Quit from the application menu, or by using the standard keyboard shortcut.

Quit the Server-Side Application

You notice that in Eclipse, the server-side appication is still running. When you quit the client side application, the server simply discarded any Objects associated with that instance of client-side application including Sessions, EditingContexts and EOs. You should now stop the server-side application.

Add an EOModel File

Drop an EOModel into the project's Resources directory.

Set WOLips to generate required files

In order for the EOAssistant to be able to modify the user.d2wmodel file in your project root, WOLips must write out both the PB.project and .xcodeproj files when it builds. Without these checked, the EOAssistant will modify the user.d2wmodel file in your project's build directory, which will get erased any time you clean your project.

This is a work-around due to a bug in WebObject's EOAssistant. A Radar has been logged (7020811).

Fix broken Swing bindings

Using a recent JDK (> 11 LTS) will break UI bindings because of then applied Java security constraints.

To turn off these constraints even for the autostarted Java Client Application modify the responsible script at /Library/Application Support/Apple/Developer Tools/WebObjects Support/UnixLaunchClient.sh.

Look for line 227 setting the JVM options, add this option:

DEFAULT_JVM_OPTIONS="--add-exports java.base/sun.security.action=ALL-UNNAMED"

Rebuild the Java Client.