Developing exteNd Director Applications

CHAPTER 6

Using the Resource Set in an exteNd Director Application

This chapter describes the purpose of the exteNd Director resource set, what it contains, and how its configuration settings affect your exteNd Director application. It contains the following sections:

• Role of a resource set in your application

• What to put in a resource set

• Binding subsystems to a resource set

• Configuring the resource set

• Dynamic loading of resources and classes

• Using events to report resource set changes

• Validating a resource set

• Storing XML files that contain MBCS characters

Role of a resource set in your application

An exteNd Director resource set organizes descriptors and other files used by exteNd Director subsystems and provides for dynamic loading during development, avoiding frequent redeployments and speeding up your testing. Each Portal (or Portlet) application can include a resource set.

A resource set holds application-defined resources and classes. Some of these resources are templates or definitions for using a subsystem's features, such as a workflow or a portlet descriptor. Others specify how subsystems work together, such as bindings between rules and users. Resources are usually XML files; some are accompanied by Java classes.

Support for multiple resource sets   The exteNd Director subsystems provide support for multiple resource sets. Therefore, an exteNd Director EAR that contains multiple portlet application projects, each with a separate resource set. Each portlet application resource set can have its own resources (such as pageflows and workflows). These resources do not need to be copied into the resource set for the Portal WAR.

Each portlet application WARs (whether in shared lib mode, or WARs contained within an EAR) is a self-contained unit. A full portlet application can therefore be deployed without requiring a change to the Director deployment.

Artifacts in a WAR can only access other artifacts in the same WAR. This restriction reinforces the notion that each application WAR is a self-contained entity.

When you create a new resource in an EAR project that contains multiple resource sets, you need to specify which resource set to use as the target.

Finding resources   A resource set organizes your application's resources in a known directory structure, described in What to put in a resource set.

In your application, access to resources is handled by the resource servlet. These are its primary functions:

• Document discovery and retrieval

• Java class discovery

• Java class loading

Dynamic loading   A resource set can be configured to dynamically load resources from disk as well as from the deployed WAR. Configuration settings specify where to look for updated versions of resources. The resource servlet vulture keeps watch on the directory locations and determines when new classes and resources are available to be loaded. To set up dynamic loading, see Dynamic loading of resources and classes.

Resources tab   When you are developing your application, you can use the Resources tab in the Navigation Pane to find the resources you want to work on. For more information, see Searching a Resource Set.

Including a resource set in your exteNd Director application   In an exteNd Director EAR project, a resource set is part of an application WAR within the EAR. In an exteNd Director WAR project, the resource set is added as a JAR file in the WEB-INF\lib directory. A resource set is required for a WAR project—but is not required for an EAR project.

What to put in a resource set

When you create a Portal (or Portlet) application that includes a resource set, the WAR contains the resource set servlet and a JAR file called appname_resource.jar that contains directories for the resources required by your exteNd Director application. The resource JAR is located in the WEB-INF\lib directory of the WAR.

The resource JAR contains Java classes for portlets, conditions, and actions you create, as well as XML descriptor files that provide application metadata. The resource JAR can also contain custom resources that you define. When you use exteNd Director to create new resources of various types, the exteNd Director wizards save the resources in the appropriate directories of the resource JAR.

In addition to appname_resource.jar, you can add other JAR files to WEB-INF\lib. Any resources in those additional JARs must be stored in the subdirectory that corresponds with the resource type. Each JAR needs to be listed in the resourcePath and/or libPath in the resource set's configuration file.

Subdirectories for resources and Java classes

The following table lists the directories in a resource JAR and the types of resources they can contain. When you look at the project in Source Layout, you will find these subdirectories under the data directory:

Using views to find what you're looking for   You can use views to display personalized lists of items within an exteNd Director project. Views can be used to look at resources in a resource set. exteNd Director ships with several predefined views. In addition, exteNd Director allows you to define custom views to display project items that are of particular interest to you. For details on using views to find items in an exteNd Director project, see Working with Views.

Projects for a resource set

A Portal (or Portlet) application with a resource set consists of at least two projects, which you see in the Source Layout:

• A WAR project

• A JAR project in the WEB-INF/lib directory of the WAR

The web.xml descriptor for the WAR projects configures the resource servlet. The JAR project has a data directory and a source directory that are used to build the resource JAR. Additional resource JARs can be included as built JARs or as projects whose JARs are built with the current project.

Binding subsystems to a resource set

How binding works   Subsystems that use resource sets are bound to them by entries in the following XML files:

• resourceset.xml in the WEB-INF/conf directory of a WAR

• config.xml for the subsystem service JAR

The resourceset.xml file specifies a name that other modules use to refer to the resource set. You can change the name by editing the value of this setting:

  <settings>
     <name>appname-ResourceSet</name>
     ...
  </settings>

    For information about resourceset.xml, see Configuring the resource set.

For a subsystem that uses resources, its config.xml file binds the subsystem to a particular resource set by specifying the resource set name in a property key/value pair. The binding for the rule subsystem looks like this:

  <property>
    <key>RuleService/resourceset</key>
    <value>appname-ResourceSet</value>
  </property>

Editing the binding   There are two ways to edit the binding:

• Use the Configuration tool (Project>Director Project>Configuration)

      For information, see Reconfiguring exteNd Director Projects.

  OR

• Edit a subsystem's config.xml

TIP:   Use the View tab on the Resources panel in the Navigation Pane to find configuration files. Try these views:

• settings.war.xml for a WAR project (or settings.ear.xml for an EAR project)

• config.services.by.subsystem.war.xml for a WAR project (or config.services.by.subsystem.ear.xml for an EAR project)

Binding and the Project Wizard   When you use the Project Wizard to create a new Web application that includes a resource set, the wizard sets the subsystem bindings to point to the new resource set. You use the methods just described to reset them, if you want.

Configuring the resource set

A Web application with a resource set has two configuration files:

• web.xml

• resourceset.xml

About web.xml   The web.xml descriptor contains the standard settings for a WAR. It identifies the servlets that the resource set uses. It doesn't hold any resource set configuration settings.

About resourceset.xml   The resourceset.xml configuration file has settings that specify how to find resources and what JARs are enabled, as well as variables that you can use when setting values.

The rest of this section describes the settings you can make in resourceset.xml, showing the XML. In the Resource Set Editor, you can use the graphical view so you don't have to edit the XML directly.

    For information on using the Resource Set Editor, see Editing the Configuration of a Resource Set.

Variables

The variables section of resourceset.xml defines local variables that you can use (instead of static values) when defining configuration settings. Variables can be used to identify whether a subsystem is installed and active. Variables can also be used for directory paths. In a newly created resource set, several variables are defined for you. You can add additional variable definitions.

The variables section has this XML format:

  <variables>
     <variable key="EARLOCATION" value="C:\DirectorProjects\Test2\Ear" />
     <variable key="WARLOCATION" value="C:\DirectorProjects\Test2\Ear\MyApp" />
     <variable key="ACCESS_DISK" value="true" />
     <variable key="LIBRARY" value="../library" />
     <variable key="WEBINF" value="WEB-INF/lib" />
     <variable key="NEVER" value="0" />
     <variable key="FREQUENT" value="7500" />
     <variable key="INFREQUENT" value="15000" />
  </variables>

NOTE:   The EARLOCATION variable is not included in WAR projects.

These variables are defined for you:

General settings

General settings for the resource set include its name and flags that enable validation, logging, and dynamic loading.

The settings section of resourceset.xml has this format:

  <settings>
     <name>appname-ResourceSet</name>
     <dynamicClassLoading>true</dynamicClassLoading>
     <validate>false</validate>
     <verbose>false</verbose>
     <vultures>true</vultures>
  </settings>

These general settings are as follows:

Types and locations of resources: resourcePath and libPath

The path-entries section of resourceset.xml specifies two paths: resourcePath and libPath.

resourcePath   The resourcePath tells the exteNd Director application where to find resources. For resourcePath, you specify:

• What types of resources to load. A set of ext elements identify the file extensions associated with resource types.

• Where to find resources. A set of entry elements identify JARs and disk locations that contain resources. Resources may be dynamically loaded from disk locations and reloaded when they change.

libPath   The libPath tells the application where to find Java classes. The resource set class loader looks for classes in particular locations and can dynamically load and replace classes that have been loaded previously. For libPath, you specify:

• What classes are loaded via the normal class loader. A set of filter elements identify the packages that contain these classes, typically the packages of the exteNd Director API.

• What file extensions identify Java code—typically just .class.

• Where to find Java code in JARs and disk locations. A set of entry elements identify JARs and disk locations that contain Java classes. Classes may be dynamically loaded from disk locations and reloaded when they change.

NOTE:   Classes you want to load from disk locations must not be included in the EAR or WAR. When you use dynamic classloading, you need to make the projects that include the classes inactive.

Example   The path-entries section has this XML format:

  <path-entries>
     <resourcePath>
        <exts>
           <ext active="true">.xml</ext>
           ...
        </exts>
        <entries>
           <entry active="true">$WEBINF$/RuleCA.jar</entry>
           ...
           <entry active="!$vultures$">$WEBINF$/appname-resource.jar</entry>
           <entry active="$vultures$" vultureInterval="$FREQUENT$"
                  recursive="true">$WARKLOCATION$/data</entry>
           ...
        </entries>
     </resourcePath>
  
     <libPath>
        <filters>
           <filter active="true">com.sssw.fw</filter>
           ... 
        </filters>
        <exts>
           <ext active="true">.class</ext>
        </exts>
        <entries>
           <entry active="true">$WEBINF$/CQA.jar</entry>
           ...
           <entry active="!$vultures$">$WEBINF$/appname-resource.jar</entry>
           <entry active="$vultures$" vultureInterval="$FREQUENT$"
                  recursive="true">$WARLOCATION$/build/resource-classes</entry>
           <entry active="!$productionMode$" vultureInterval="$FREQUENT$"
                  recursive="true">$DISKLOCATION$/ResourceSet/WEB-INF/lib</entry>
        </entries>
     </libPath>
  </path-entries>

The table describes the elements in the path-entries section:

  <filter active="true">com.sssw.fw</filter>

  <ext active="true">.xml</ext>

  <entry active="true">$WEBINF$/CQA.jar</entry>
  <entry active="true">$WEBINF$/resource.jar</entry> 
  
  <entry active="true" vultureInterval="$FREQUENT$" recursive="true">$WARLOCATION$/data</entry> 
  
  <entry active="true" vultureInterval="$FREQUENT$" recursive="true">$WARLOCATION$build/resource-classes</entry>

Using variables in entry elements

Several useful variables are defined for you in the variables section, including the disk location of the EAR and WAR. You can also use general settings as variables.

    For a list of general settings, see General settings. For a list of variables, see Variables. You can define additional variables as needed to make your resource.xml dynamically configurable.

Editing tips   When editing XML and paths, include a $ before and after the name of a variable or general setting. In the Resource Set Editor, right-click check boxes to select from a list of variables.

Examples   This entry refers to the resource.jar in the resource set. $WEBINF$ specifies the WEB-INF/lib directory of the resource set WAR:

  <entry active="true">$WEBINF$/resource.jar</entry>

This entry refers to a disk location within the exteNd Director project directory where Java classes are compiled. A vulture interval has been set—so as items are recompiled, they will be dynamically loaded:

  <entry active="true" vultureInterval="$FREQUENT$"
   recursive="true">$WARLOCATION$/build/resource-classes</entry>

This entry refers to the disk location where resources are stored in the WAR. The subdirectories will all be searched recursively—and as resources change, they will be dynamically loaded:

  <entry active="$vultures$" vultureInterval="$FREQUENT$"
   recursive="true">$WARLOCATION$/data</entry>

Directory keys for indexing

exteNd Director uses indexes of the resource set content to figure out what to display in the Resource Set tab of the Navigation Pane. Both the Relationship Viewer and the Resource Set Search provide useful ways of looking at your project's content, and the directories section of resourceset.xml defines ways for looking at the content.

Files in the resource JARs and disk locations are always indexed by their file names. For each of the standard resource set directories, resourceset.xml can define additional ways of categorizing the resources or classes. You can define additional search indexes, and you can add indexes for custom directories in the resource set.

Indexing and searching are features that enhance your work environment; they are not used in your deployed exteNd Director application.

The directories section has this XML format:

  <directories>
     <directory name="rule-condition-macro" active="true">
        <search key="name" valuebased="true" xpath="/conditionmacro[@name]" active="true" />
     </directory>
     ...
  </directories>

The table describes the elements contained in the directories section:

  <directory name="rule-condition-macro" active="true">

  <search key="name" valuebased="true" xpath="/conditionmacro[@name]" active="true" />

Dynamic loading of resources and classes

exteNd Director supports dynamic loading of resources and classes within a resource set. Dynamic loading speeds development, because you can test changes in the resource set without having to deploy the whole project. You can also allow controlled changes in a production application by enabling dynamic loading for particular resource types, such as rules.

Dynamic loading is enabled by default when you create a new project or use the Express Portal project. When dynamic loading is enabled, resource set vultures watch disk locations for changes. After a specified interval, if a file has changed, the vulture fires an event with information about the changed resource item. Listeners for that resource set can examine the resource item and determine what action to take. Default listeners are programmed to flush the changed object from the resource set cache, so that the new version will be loaded when it is first requested.

    For more about events and listeners, see Using events to report resource set changes.

exteNd Director can dynamically load resources or classes or both. Settings in resourceset.xml determine what gets loaded. Each disk location has its own vulture settings.

NOTE:   By default, the resource set is configured for dynamic loading. The necessary settings are described here so you will understand how dynamic loading works.

Configuring the resource set   To use dynamic loading for a particular resource set, you need these settings in its resourceset.xml configuration file:

1. In the settings section, set the vultures element to true. This enables the resource set to look at disk locations and discover changes.

2. If you want Java classes to be dynamically loaded, set the dynamicClassLoading element to true. Then use the Enable/Disable button to disable resource JAR projects whose classes you want to load dynamically from disk.

3. Add one or more entry elements for disk locations to the resourcePath or libPath section. Each entry specifies a disk location that contains resources or classes. For each entry element, set these attributes:

   • Set the active attribute to true.

   • Set the vultureInterval attribute to a value greater than zero.

   • Set the recursive attribute to true if the vulture should examine subdirectories too; false if subdirectories should be omitted.

    For an example of how this looks in XML, see Example below.

How vultures work   In resourceset.xml, if the vultures element in the settings section is set to true, and if an entry in the resourcePath or libPath section specifies a disk location whose vulture interval is greater than zero, an exteNd Director vulture watches that disk directory. When the vulture interval is reached, the vulture checks to see if any of the files within the directory have been modified. The vulture also checks for new files. Deleted files are not processed.

When the vulture finds a changed file in the disk location, it flushes the previous instance of the file, and the new version is loaded the next time the object is requested. Once an item has been loaded into the cache, it is not removed until the next time the server is started, or the next time the WAR is deployed.

Dynamic loading and the class loader   The Java classloader supersedes the dynamic loading of resources and classes. So if the EAR or WAR contains a class, that class will never be dynamically loaded from disk. To load classes from disk, make sure they are not included in the deployed archive. You can use the Enable/Disable Subprojects option in the resource set configuration editor to omit one or more resource JARs from the archive.

You can enable dynamic loading for helper classes used by exteNd Director classes such as portlets. If you modify the helper classes, the classes are vultured and loaded into an instance of the class loader. However, the portlet may have been loaded by a previous instance of the class loader. In this case, it will continue to reference the classes found by its instance of the classloader. Therefore, if you recompile the helper classes, make sure to recompile the portlet as well, and you will get the latest version of the portlet and its helper classes.

Example   Suppose you want to dynamically load pages, portlets, and styles from disk. The XML files are stored in a directory called MyProjects\MyEAR\MyApp\data on your C drive. The Java classes for your portlets are compiled to MyProjects\MyEAR\MyApp\build\resource-classes.

To dynamically load updated versions of resources (pages, portlet descriptors, styles), you would need to add the data directory to the resourcePath section of the resourceset.xml file. For classes, you would need to add the build directory to the libPath. You would also disable the resource JAR project so that it is omitted from the archive (necessary only if you want to dynamically load classes).

For each path entry, you would set the vulture interval attribute to indicate how often you want the vulture to check the disk locations for changes. The vulture interval is expressed in milliseconds.

These XML excerpts appear in resourceset.xml:

  <resourceset>
  <settings>
    <name>ResourceSet</name> 
    <dynamicClassLoading>true</dynamicClassLoading> 
    ...
    <vultures>true</vultures> 
  </settings>
  <path-entries>
    <resourcePath>
      ...
      <entries>
        ...
        <entry active="true" vultureInterval="$FREQUENT$"
               recursive="true">$WARLOCATION$/data</entry>
      </entries>
    </resourcePath>
    <libPath>
      ...
      <entries>
        ...
        <entry active="true" vultureInterval="$FREQUENT$"
               recursive="true">$WARLOCATION$/build/resource-classes</entry> 
      </entries>
    </libPath>
  </path-entries>
  ...
  </resourceset>

Using events to report resource set changes

As you've learned, a resource set holds its resources and classes in JARs and on disk. These locations are listed in resourceset.xml in the resourcePath and libPath sections. The contents of a resource set can change when you add or remove files from the disk locations. To recognize and act on changes, you can configure exteNd Director vultures, described in Dynamic loading of resources and classes.

When a vulture notes a change, it fires an UPDATE event. exteNd Director subsystems can listen for resource set events and react appropriately.

This section describes how to configure an event listener and what to do to handle the event.

NOTE:   This information about resource set events is an advanced topic. The standard listeners are already configured for you. They provide the only required functionality, which is resource set caching.

Working with listeners

Listeners configured for you

In a new exteNd Director project, the Rule, Workflow, and Security subsystems are each configured with a resource set listener that is registered during the boot process. They receive events for their bound resource set.

These subsystems each have a listener class called com.sssw.<subsystem>.core.EboResourceListener, which extends com.sssw.fw.resource.EboResourceListener. These default listeners handle caching of classes and resources, so in most cases you will want to continue to use these listeners. You can add as many additional listener classes as you need.

Binding

Currently, a subsystem is bound to one resource set in a one-to-one relationship. A listener you register for a subsystem gets events for the one bound resource set. Changes to that resource set cause any registered listener's stateChanged() method to be called.

Adding a listener

There are two ways to add a listener for a resource set:

• Configure a listener service in a subsystem's services.xml. The listener is registered during the boot process.

  OR

• Call the addStateChangeListener() method of EboResource to register a listener.

The listener is a class that implements com.sssw.fw.util.EbiStateChangeListener.

Adding a listener during startup

To register a listener during startup, you include a service element in the services.xml file for the subsystem. For example, this XML registers the default listener for the rule subsystem:

  <service>
    <interface>com.sssw.re.core.EboResourceListener</interface> 
    <impl-class>com.sssw.re.core.EboResourceListener</impl-class> 
    <description>RuleService ResourceSet Listener</description> 
    <max-instances>1</max-instances> 
    <startup>A</startup> 
  </service>

The impl-class element specifies the listener class that implements the methods of EbiStateChangeListener. For a listener service, the interface is typically the same as the class.

The startup element has a value of A, for autostart—meaning it will be registered during the boot process.

Timing issues during startup   During the boot process, the target object may not be instantiated when a registration request occurs—so exteNd Director uses a delayed registration procedure that records the registration request and registers the listener after the target resource set is instantiated. When the registration occurs, a stateChanged event is fired with a status of EboState.REGISTER.

Adding or removing a listener in your code

To add a listener in your application code, you call the static method addStateChangeListener() of com.sssw.fw.resource.EboResource. The arguments are:

• Name of the resource set

• Listener class that implements com.sssw.fw.util.EbiStateChangeListener

For example, this code adds the current class as a listener for the MyResources resource set:

  EboResource.addStateChangeListener("MyResources", this);

To remove a listener, call the removeStateChangeListener() method. This code removes the current class as a listener for the MyResources resource set:

  EboResource.removeStateChangeListener("MyResources", this);

If the class you specify is not a registered listener, the remove request is ignored.

Types of events

Resource set events are stateChanged events, reporting changes in the status of the resource set. Status codes for the various states are defined in com.sssw.fw.util.EboState. A resource set generates two types of events:

• EboState.REGISTERED  Reported when the event listener is registered

• EboState.UPDATE  Reported when a change happens in one of the watched disk locations in the resource set

An EboResourceEvent object is passed to the stateChanged event. It consists of the resource element that changed and an EboState status code.

Firing an event   You can also fire stateChanged events to all of a resource set's listeners. The event can use your own application-specific status codes or the EboState codes.

This sample code illustrates how you might prepare for and fire an event. The resource set is named MyResources:

  EboResource rs = EboResource.getLoaded( name );
  EboResourceElement rsrcElem = rs.findResourceElement( file );
  EboResourceEvent rsrcEvt = new EboResourceEvent( rsrcElem, MYSTATUSCODE );
  EboResource.fireStateChanged("MyResources", rsrcEvt );

What listeners do

Behavior of the standard listeners   Each subsystem that uses resources has a standard listener that responds to changes in resource sets. The services.xml file for the subsystem sets up the registration of the listener.

If the resource set's vultures are turned on and a vulture notes that a change has occurred in a disk location, the vulture fires the listener's stateChanged event and passes an EboResourceEvent object containing a reference to the changed object. The listener code finds out if the changed object is relevant to that subsystem—and if so, flushes the old version of the resource from the subsystem's internal cache.

NOTE:   To preserve the dynamic loading of resources, do not change the configuration of the standard listeners.

Writing your own listener   Your listener class must implement the class com.sssw.fw.resource.EboResourceListener. Its only method is stateChanged() with an argument of type EboResourceEvent. The following sample code checks for this, then gets the resource element from the event object and takes some appropriate action.

The stateChanged method might look like this:

  public void stateChanged(EboEvent eo)
  {
    if (eo instanceof EboResourceEvent)
    {
      EboResourceEvent evt = (EboResourceEvent) eo;
      if (evt.getState() == EboState.REGISTERED)
      {
        ... // Code to respond to getting registered, if any
      }
      if (evt.getState() == EboState.UPDATE)
      {
        EboResourceElement elem = evt.getResourceElement();
        if (elem != null )
        {
           if (elem.getDirectoryName().startsWith("rule")
           {
  	 	         ... // Do something for a rule resource element
           }
        }
      }
    }
  }

Validating a resource set

When instantiating a resource set, exteNd Director can run validation classes to check the resource set.

NOTE:   Validation of a resource set is an advanced topic. You can enable validation in resourceset.xml and use the default validation with no further effort on your part.

The default validation checks the existence of:

• All items on resourcePath and libPath

• All portlet classes referred to in portlet descriptors

If the validate setting of the resource set is true, then during the boot process, when the resource set is instantiated, exteNd Director runs all the validation classes it finds in the resource set. They are called in no specific order.

Writing your own validation class   You can write your own validation classes to check whatever needs checking in your application. These classes can be stored anywhere in the resource set JARs.

Your validation class must implement the com.sssw.fw.resource.api.EbiValidator interface. The interface contains one method:

  public void validate( com.sssw.fw.resource.EboResource resource ) throws Exception;

If a validation class throws an exception, exteNd Director will display a stack trace on the console, then proceed with the next validation class. An exception does not stop the validation process or prevent the exteNd Director application from running. All you need to do is be aware that the information on the console could indicate problems in your application. It is up to you to take further action.

Running a validation test   In exteNd Director, you can run the resource set validation before you deploy:

1. In the WEB-INF/lib directory of the resource set, find and open resourceset.xml.

2. In the graphical view of the editor, select the General tab.

3. Click the Validate button.

   Any output from the validation classes is displayed in the editor's output window.

Storing XML files that contain MBCS characters

If you want to store XML files in a resource set that contains extended ASCII or multibyte character set (MBCS) characters, you need to add an XML header to these files that specifies the correct encoding for the locale. If the machine's locale is France, for example, the encoding should be ISO8859-1. In this case you would need to add the following header to each XML file stored in the resource set:

  <?xml version="1.0" encoding="ISO8859_1" ?>

If this header is missing, the data will not be parsed correctly by the XML parser.

Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved.  more ...