Rule System Priorities

Each rule system rule has a priority, which is a mechanism to manage conflicting rules. It is possible to have two rules with the same condition (left-hand side), the same key (right-hand side), but a different value (right-hand side). To handle this conflict, the rule with the higher priority is fired.

The default rules provided by the com.webobjects.eogeneration package have a priority of 0. The Direct to Java Client Assistant gives its rules a priority of 100. You should never change the priority of rules generated by Assistant (this would involve editing the user.d2wmodel file, which is never a good idea since Assistant writes it out each time it saves). Also, the rules you create by hand should not have a priority of 100, since this confuses Assistant. If you want the rules created by Assistant to be preferred over your own rules, use a lower priority like 50. Otherwise, give your rules a higher priority.

D2WComponents

There is a one-to-one correspondence between Direct to Java Client D2WComponent subclasses (server side) and EOController subclasses (client side). For example, an EOTextFieldController (inheriting from EOController) on the client has a corresponding D2WComponent class on the server also named EOTextFieldController (inheriting from D2WComponent). The client-side class displays and manages user interface widgets while the server-side class generates XML to describe the client-side user interface.

The server-side D2WComponents for Direct to Java Client applications can be found in /System/Library/Frameworks/JavaEOGeneration.framework/Resources. You can open the components in WebObjects Builder to learn more about them.

Rule System Requests

The user interface components of a Direct to Java Client application are generated by the rule system when needed. The controller factory makes rule system requests as each new window in the client application is activated.

When an application starts up, the controller factory makes requests for the following keys:

• availableSpecifications, which tells the controller factory all the specifications (request keys such as window and modalDialog, and any custom request keys)

• defaultSpecifications, which tells the controller factory which windows to open automatically once the application is finished initializing

• actions, which tells the controller factory what actions to add to the main menu along with standard menu items such as Quit

Then, to generate the controller hierarchy for a window or modal dialog, the controller factory makes requests for the following keys:

• window, which returns the controller hierarchy XML for a window the application will open; the request from the controller hierarchy must also provide state information such as a task and, optionally, an entity name so the rule system can determine what window is being generated

• modalDialog , which returns the controller hierarchy XML for a modal dialog the application will open; again, the request from the controller hierarchy must also provide state information such as a task and, optionally, an entity name

Internal Rule System Requests

When the rule system evaluates a request from the controller factory, the actual returned value is the name of a D2WComponent, not the controller hierarchy XML. The D2WComponent identified by the fired rule is responsible for generating the controller hierarchy XML that the controller factory receives.

In the process of generating XML, the D2WComponent objects might require the rule system to evaluate additional requests, the most significant of which are these two:

• controller, which identifies a controller (a D2WComponent) for a task identified in the request’s specification; the entity-level controller defines the part of a window or dialog user interface for performing the specified task on the specified entity

• propertyKeys, which identifies the property keys for a task and an entity identified in the request’s specification; the property keys are needed to identify the additional controllers needed to display and manipulate an object’s attributes and relationships

Sometimes it is necessary to know what kind of controller the rule system asks for. All the default rules therefore put additional information on the D2WContext (and you should maintain this information if you customize rules). This information can be used as additional criteria in the rule qualifiers. These are the two categories of controllers:

• controllerType , (possible values: actionWidgetController, dividingController, groupingController, entityController, modalDialogController, tableController, widgetController, windowController)

• isRootController, (false if not, nil otherwise)

Generating the Student Form Window

As an example of how the Direct to Java Client D2WComponent classes work, consider the form window for the Student entity in the tutorials. Suppose a user clicks the New button in a Query window for the Student entity. The controller factory then makes a request to the rule system with the following specification:

question = window, entity.name = Student, task = form

This specification tells the rule system that for the form task for the Student entity it should evaluate the window key and return a controller hierarchy based on what the window key evaluates to in the rule system.

The default rule fired to satisfy this request is as follows:

Left-Hand Side:

*true*

Key:

window

Value:

"EOWindow"

Priority:

0

You could write a custom rule (and give it a higher priority) to, for example, associate an EOModalDialog with the window key rather than the default EOWindow. Since in this case the default rule is not overridden, the D2WComponent that generates the XML for the form task for the Student entity is EOWindow (a WebObjects component).

Open EOWindow.wo in WebObjects Builder. (You can find it in /System/Library/Frameworks/JavaEOGeneration.framework/Resources).

EOWindow.wo contains a .html file (containing XML) and a .wod file.

Here’s an excerpt from EOWindow.html:

    <WEBOBJECT name=windowController>

        <WEBOBJECT name=actionWidgetController>

            <WEBOBJECT name=taskController>

            </WEBOBJECT>

        </WEBOBJECT>

        <WEBOBJECT name=content>

        </WEBOBJECT>

    </WEBOBJECT>

And here’s an excerpt from EOModalDialog.wod:

windowController: EOSwitchComponent {

    componentNameKey = "windowController";

    d2wContext = localContext;

    controllerType = "windowController";

}

The EOSwitchComponent in the .wod file is a dynamic element that makes a new rule system request using the componentNameKey as the request key. So in the case of windowController, the switch component makes a new rule system request with the key windowController, the name of the componentNameKey binding.

Before making the request, however, the switch component updates the rule system’s state information. Generally it creates a new D2WContext based on the state information in the old D2WContext. That’s what the d2wcontext binding specifies. Bindings other than componentNameKey and d2wcontext identify additional state that the switch component adds to the new D2WContext. For windowController, the additional state is simply that the controllerType is windowController.

In this manner, the XML controller hierarchy is built recursively using switch components.

One of the leaf nodes in the Student form window is for an EOFormController whose .wod file looks like this:

content: WOComponentContent {

}

controller: WOXMLNode {

    elementName = "FORMCONTROLLER";

    alignmentWidth = d2wContext.alignmentWidth;

    alignsComponents = d2wContext.alignsComponents;

    archive = d2wContext.archive;

    className = d2wContext.className;

    displayGroupProviderMethodName =       d2wContext.displayGroupProviderMethodName;

    editability = d2wContext.editability;

    editingContextProviderMethodName =       d2wContext.editingContextProviderMethodName;

    entity = controllerEntityName;

    horizontallyResizable = d2wContext.horizontallyResizable;

    iconName = d2wContext.iconName;

    iconURL = d2wContext.iconURL;

    label = d2wContext.label;

    minimumHeight = d2wContext.minimumHeight;

    minimumWidth = d2wContext.minimumWidth;

    path = controllerRelationshipPath;

    prefersIconOnly = d2wContext.prefersIconOnly;

    transient = d2wContext.transient;

    usesHorizontalLayout = d2wContext.usesHorizontalLayout;

    verticallyResizable = d2wContext.verticallyResizable;

}

disabledActionNamesArray: EOSwitchComponent {

    componentName = "EOStringArray";

    array = d2wContext.disabledActionNames;

    name = "disabledActionNames";

}

mandatoryRelationshipPathsArray: EOSwitchComponent {

    componentName = "EOStringArray";

    array = d2wContext.mandatoryRelationshipPaths;

    name = "mandatoryRelationshipPaths";

}

A WOXMLNode is a component that generates XML for a node in the controller hierarchy. Its bindings tell the server-side D2WComponent how to configure its client-side counterpart. For example, the binding names in the EOFormController .wod file correspond to XML attributes understood by the client-side EOFormController. Correspondingly, the binding values are the values assigned to those XML attributes. Most of the bindings are set to a key path starting with “d2wContext”. These key paths refer to the state information stored in the D2WContext.