Core Development Guide

Chapter 7   Configuring a Director Application

This chapter explains how to use Director wizards in the SilverStream eXtend Workbench to create and configure Director applications. It contains the following sections:

• About configuring Director applications

• Creating a new Director EAR project

• Reconfiguring your Director EAR

• Editing the configuration of a resource set

About configuring Director applications

A Director application is packaged in a single Director EAR file that contains several WAR files and JAR files. You can create the EAR by running the Director EAR Wizard in Workbench. The wizard lets you select the subsystems you want to use and specify configuration properties for these subsystems. In the wizard, you also configure a custom Web application module that will hold your application code. After you've finished making your selections, the wizard creates an EAR project that includes the J2EE modules you need for your application.

Once you've run the wizard, you can add additional application-specific J2EE modules to the EAR. You can also add or remove subsystems or make any other necessary changes to the structure and content of the EAR, just as you would with any J2EE application.

When you're ready to deploy the application, you can use the facilities provided with Workbench to upload the EAR to one or more servers.

Basic steps   Here are the general steps you need to follow to configure a Director application:

1. Install Workbench and Director.

   The Director installation program adds several extensions to Workbench. It also installs the standard Director template that you can use as the basis for creating your Director EAR projects.

       For installation instructions, see the Release Notes.

2. If you will use the Search subsystem, configure the Autonomy DRE.

       For instructions, see the Search Guide.

3. Create a new database for your Director application, and if your JDBC driver expects it, define an ODBC data source name (DSN) for your newly created database. Director uses a default name of Director for the data source, but you can use your own name.

   This database holds Director data tables for several of its subsystems.

   On a SilverStream server, this can be different from the deployment database. A typical scenario is to deploy the Director EAR to the SilverMaster database with a separate database for Director data.

       For instructions, see your DBMS documentation.

4. Create a new Director EAR project using the Director EAR Wizard with a Director template.

       For instructions, see Creating a new Director EAR project.

5. Set up dynamic loading so that you can test application resources without frequent redeployments.

       For instructions, see Dynamic loading of resources and classes.

6. Do the required deployment setup for your server. Some setup is done in Workbench; for the rest, you use your server's tools.

7. Deploy the application to provide access to Web-tier Director tools.

       For instructions, see Deploying a Director Application.

Creating a new Director EAR project

You create a new Director EAR project with the Director EAR Wizard, which is available in eXtend Workbench after you've installed Director. The Director EAR Wizard uses a Director template as the basis of your project.

About templates   A template is a collection of subsystems (which may have custom configurations) and application modules. Each template exists in a template directory on your file system. Various subsystem directories and other files are in that template directory. The wizard copies files from the template to create your project.

A template may include a Workbench project file (with the .SPF extension) for a Director EAR, but the project file is not required. If the template includes a project file, you can open the template project and continue developing it.

Limitations to templates   In the wizard, you can start from any existing Director project, making it your template, and your project can be a template for another application. However, this hierarchy of source templates doesn't provide ongoing inheritance. Once your project is created (by copying the modules and components from the template to the new project), there is no further connection to the source template. Changes made to a template are not reflected in existing projects that were derived from that template.

Available templates   The basic Director template makes all application functionality available in the wizard:

In the Director wizards, the template location can also be the root directory of any Director EAR project.

Typical versus custom setup   What you get from a typical setup depends on the template you choose. From the basic Director template, your project gets all of the J2EE archives and components required to use the following subsystems:

• Content Management

• Debug

• Directory

• Framework

• Portal

• RSS

• Rule

• Search

• Security

• User

• WebDAV

• Workflow

Typical setup from the Director template also provides the following Web tiers:

• PAC

• PMC

Custom setup from the Director template lets you choose which of the subsystems and Web tiers will be part of your project.

Both typical and custom setup provide a panel for configuring a custom Web application. If you include a resource set, then subsystems that have a resource set binding in their configuration file are bound to this resource set.

In additional to the panels described in the following procedure, you may see other panels that have been designed for the template you choose.

To create a new Director EAR project:

1. In eXtend Workbench, select File>New Project.

   The New Project dialog appears.

2. Select the Director tab, then choose Director EAR and click OK.

   

3. On the Template Location panel in the Director EAR Wizard, specify the full path for a directory that contains the template you want to use. You can specify one of the following:

   • The standard Director template (templates\Director in the Director install directory)

   • Another template you've installed or created

   • The root directory of a Director project

   

   You can type the path of a template directory or click the Browse button to select a directory on your file system.

   After you've made your selection, click OK. Then on the Template Location panel click Next.

4. When the wizard prompts you, click Yes to confirm your template choice.

   

   The wizard takes a minute to scan the template directory for a list of available subsystems. Then it displays the Project Information panel.

5. In the Project Information panel, fill in the following fields.

   TIP   If you fill in the fields in order, subsequent fields are filled in automatically with useful default values.

   Project setting	What you do
   Project Name	Specify the name you want to use for the project file (the .SPF extension is automatically appended). In Workbench, the Navigation Pane's Source Layout displays the project name. As you enter a project name, the archive name is filled in automatically.
   Project Location	Specify a root directory for the project. You can type a path and/or use the Browse button to select a directory location. The location doesn't have to exist yet. As you enter a project location, the archive location is filled in automatically. If you do not specify an absolute path, the wizard locates the project under the Workbench bin directory. The wizard copies template files and subdirectories to this location.
   Archive Name	Specify the name of the archive file that will be generated. The .EAR extension is automatically added. In Workbench, the Navigation Pane's Archive Layout displays the archive name. You can keep the default archive name (which matches the project name) or enter a new one.
   Archive Location	Specify a directory location for the project archive or accept the default, which is the Project Location.
   J2EE Version	Select j2ee 1.2 (ear 1.2).

   A filled-in panel might look like this:

   

6. When you finish the project settings, click Next.

   If the directories you specified do not exist yet, the wizard asks permission to create each of them.

   

7. Click Yes to confirm each new directory.

   The wizard displays the Setup Type panel.

   

   You have a choice of these setup types:

   Setup type	What the wizard does
   Typical	Copies all the subsystems in the template to your project directory and uses default values for most configuration options. You can make some configuration choices.
   Custom	Lets you choose which subsystems the wizard will copy to your project directory and provides panels for setting their configuration options.

8. On the Setup Type panel, select the type you want and click Next.

   If you select Custom, the wizard displays the Subsystem Selection panel so you can select the subsystems you want. If you select Typical, skip to Step 10.

9. On the Subsystem Selection pane, select the subsystems you want then click Next.

       For descriptions of the Director subsystems, see About SilverStream eXtend Director.

   If you try to eliminate a subsystem that is required by another selected subsystem, a dialog tells you what subsystems depend on the one you're trying to omit. You have to omit those dependent subsystems before you can remove the subsystem that they require.

   

   The wizard displays the Custom Web App panel, where you specify options for the WAR that will contain your application code.

10. On the Custom Web App panel, make these settings for the WAR, then click Next.

    Custom WAR setting	What to specify
    Create a Custom Web App now?	Select Yes to add a WAR for your custom application functionality. If you select No, you can add one later with the Custom Web App Wizard (described in Adding a custom Web application to the EAR).
    Name	The context name for the WAR. This is used in URLs for pages of your application.
    Type	Select ResourceSet or Portal check boxes to specify whether the WAR will include this Director functionality. Note that you can't select Portal without including Resource Set. Resource sets enable dynamic loading of descriptors and classes and are required by some subsystems, such as Rule and Portal. Portal provides login, pages with components, user-defined pages, and coordinated themes for page design.     For information about Director portals, see the Portal Guide. For information about resource sets, see Using the Resource Set in a Director Application.
    Resources	Select the component collections, tag libraries, and conditions and actions for rules that you want to include in your application WAR. The list of available resources depends on the subsystems you've selected. Some resources are required by other functionality you may have selected. For example, if you select Portal, you also need to include Core Components.     For information about components provided with Director, see Samples.
    Template Resources Location	A location for storing available resource that you can add to the project later. By default, this is the TemplateResources directory of the template. You can specify a different location and Director will copy available resources and make them available if you run Director Setup later.

    

    The wizard displays the Namespace Application panel.

11. On the Namespace panel, enable namespacing by entering a namespace context and making sure the Yes check box is selected (selected by default).

    The namespace is used in the URL for your Director application. The default is the project name.

    Namespacing allows you to deploy multiple Director EAR files to the same server when those applications have similar URLs and content. For example, if you deploy the PAC in several different EAR files to the same server, the application server will not be able to distinguish the different versions of the PAC unless EAR namespacing is enabled. If you won't have conflicting applications, you can disable namespacing so that your application's URL is shorter.

        For more information about namespacing in a Director application, see EAR namespacing.

    

12. Click Next to go on to the next panel.

    If you selected the Content Management subsystem, the wizard displays the Content Management Search Configuration panel, which has three tabs.

    If you didn't select Content Management, go on to Step 15.

    

13. On the Repository tab, you can make these settings:

    Configuration setting	What to specify
    Enable link to the search service?	Select Yes if you want to use the Autonomy search capabilities with the Content Management subsystem. Important   If you enable search (the default), make sure you configure the Autonomy DRE to run with your server, as described in the Search Guide. Otherwise, features of the Content Management subsystem and the PMC will be disabled.
    Query Engine Host Name	Specify the host name or IP address of the Autonomy DRE (Dynamic Reasoning Engine). The default is localhost.
    Query Port	Specify the port number on which the DRE expects to receive queries. The default is 2000.
    Index Port	Specify the port number the DRE uses for indexing. The default is 2001.
    Repository Name	Specify the name of the content management repository. The value is always Default.

    On the Synchronization tab you can make these settings:

    Configuration setting	What to specify
    Synchronization Mode	Specify how changes to documents are made known to the DRE. Values are: immediate — Propagates changes when they occur; recommended when there is a low volume of document additions and updates batch — Propagates changes to the DRE as a scheduled background task; recommended for environments with a high frequency of changes
    Operations that cause immediate synchronization	When synchronization mode is immediate, select the operations that cause changes to propagate to the DRE. Use the arrow buttons to move operations to and from the Available and Selected lists. For performance reasons, you may not want all operations to be synchronized immediately.
    Number of deleted documents to batch up	Specify the number of documents to be deleted as a batch. Deleted documents are done as a batch regardless of synchronization mode.

    On the Filters tab you can make these settings:

    Configuration setting	What to specify
    Binary document text filter directory	Specify where to find the Autonomy filters for importing documents that have a binary file format. The default location is Director-install-dir\Autonomy\OmniSlaves.

    Then click Next.

    If you selected Typical setup, skip to Step 15 for the Directory Configuration panel.

14. On the Content Management Caching Configuration panel, make the settings you want, and click Next.

    Configuration setting	What to specify
    Cache Fields?	Select the types of objects you want to cache. Usually you will want to cache all object types. Caching is efficient because the application makes fewer SQL queries of the database. If there are constraints on memory usage, you may choose not to cache. Content management caching is not related to PAC cache settings.
    Cache Doc Types?
    Cache Folders?
    Cache Categories?

    The wizard displays the Directory Configuration panel.

15. On the Directory Configuration panel, select a server-specific security realm. Then click Next.

    The realm must match the server to which you will deploy.

    TIP   Select SilverStream (compatible) if you have a user list from a previous version of Director on the target server.

        If you want to change servers after you set up your project, see Changing your deployment configuration.

    

    The wizard displays the Framework Configuration panel.

    

16. On the Framework Configuration panel, specify values for these framework settings:

    Framework option	What you do
    Director Framework Datasource	Specify the JNDI name for your application's database. The database contains Director application data such as content and user information. The value you specify depends on the target application server. On SilverStream, the JNDI name includes qualifiers around the database name, like this: Databases/Director/DataSource. If your database is not named Director, substitute its name between the qualifiers. For example, if your data source name is MyDB, specify Databases/MyDB/DataSource. NOTE   Note that the application database can be, and usually is, different from the deployment database, which typically is the SilverMaster database. On WebLogic and WebSphere, the JNDI name does not need extra qualifiers. Replace the suggested value with the JNDI name for the database. For example, for a data source named MyDB, specify MyDB.
    Locksmith	To use ACL-based security, specify the user ID for administering security using the PAC. The ID you specify must exist in the server's user realm when you deploy the Director EAR. NOTE   If you do not want to use ACL-based security, you must change the Locksmith to anonymous to prevent ACLs from being set up for the Director Admin elements.

17. Specify values for these cluster options:

    Cluster option	What you do
    Do you want to use clustering?	Select Yes to enable Director support for clustering. The server you deploy to must already be set up as part of a server cluster.
    Host	Specify the URL of the server that will run the Director Cache Coordinator. NOTE   You must use the Director installation program to install the Cache Coordinator on the server.
    Port	Specify the RMI port number that the Cache Coordinator will listen on. This must be the same value you specify when you install the Cache Coordinator.

    The Generated UID field displays an application identifier used for clustering. You cannot change it.

18. Specify a writable directory for Director use:

    Option

    Value

    Server Accessible Temp Directory

    Specify a directory to which the server has write access. Director uses the directory for several types of files: Temporary files getmacaddr utility for generating unique identifiers (UIDs) for Director objects. If getmacaddr doesn't exist in the directory you specify, Director copies the utility from the FrameworkService JAR to this location. Parent folder of PortalCache The value you specify is stored in the Framework's config.xml in the key ContentCache.Disk.directory. The default is the user's TEMP or TMP environment variable.

    Then click Next.

    If you selected Typical setup, skip to Step 20 and the Summary panel. If you selected Custom setup and included the WebDAV subsystem, the wizard displays the WebDAV Configuration panel next.

19. On the WebDAV Configuration panel, you can make settings for composing an URL for WebDAV access. A user's WebDAV client program uses the context root and servlet path as its URL for accessing the WebDAV server in your Director application. You might change the default values to provide a shorter or application-related URL.

    Configuration setting	What to specify
    Service Context Root	The relative URL for the WebDAV subsystem WAR in your Director application
    Servlet Path	The WebDAV subsystem servlet in the WebDAV WAR.
    Require locks for update operation	Select the Yes check box to require that files be checked out and locked before they are moved, copied, or deleted. Locking preserves data consistency when multiple users update data. Clear the check box if your WebDAV client does not support a locking mechanism. In particular, Microsoft File Explorer does not support locking of WebFolders.

    

    Then click Next.

    The wizard summarizes the project details.

20. On the Summary panel, clear the Build project after wizard is finished check box if you don't want to build the project archives right away.

    TIP   A recently built project is necessary for editing J2EE descriptor files and for deploying Director Web-tier tools. You can let the wizard start the build process or you can select Build commands on the Project menu later.

    

21. Click Finish to create the project.

    The wizard takes some time to copy the template files to the project directory. Then it builds the project, if you selected that option.

    Now you're ready to begin work on your application.

Reconfiguring your Director EAR

There are several ways you can change your Director EAR. In Workbench, you can use these Director tools:

• Changing the configuration of various subsystems, including their resource set

• Adding subsystems from the same or another template

• Removing or disabling subsystems

• Adding a custom Web application to the EAR

Changing the configuration

After you've created a Director EAR project, configuration settings for various subsystems are stored in the subsystem's config.xml. You can use the Director Configuration tool to change configuration settings you made in the Director EAR Wizard. You can also change the binding between subsystem and resource set.

About subsystem-resource set binding    Several subsystems use data in a resource set. These subsystems use a binding setting in their configuration file to identify what resource set contains the resources they need. By default, the Director EAR Wizard and the Custom Web App Wizard set this binding to the most recently created custom Web application, if it includes a resource set.

You can change the binding for the Rule, Workflow, and Security subsystems using the Director Configuration tool, described next. Note that because of this binding only one Web application in the EAR can use rules; likewise for workflow and security roles.

To change configuration settings for your Director EAR project:

1. With your Director EAR project open in Workbench, select Project>Director EAR>Configuration.

2. In the Director EAR Configuration dialog, click the tab for the subsystem whose settings you want to change.

   Subsystem	What you can change	More information
   Content Management	Cache options and Autonomy search options	Steps 13 and 14 of To create a new Director EAR project:
   Directory	Security realm	Step 15 of To create a new Director EAR project:
   Framework	Director data source, locksmith, and clustering options	Step 16 of To create a new Director EAR project:
   Rule	Resource set binding	Binding subsystems to a resource set
   Security	Resource set binding	Binding subsystems to a resource set
   Workflow	Resource set binding	Binding subsystems to a resource set
   WebDAV	WebDAV URL and locking requirement	Step 19 of To create a new Director EAR project:

3. Click OK to save your changes.

Adding subsystems

After you have created a Director EAR, you can use the Director EAR Setup Wizard to add subsystems.

You can add subsystems from any template—you don't have to use the same template you used to create the EAR. Another template might include a subsystem that your original template didn't have. The Setup Wizard copies subsystem files to the EAR project directory, adds subprojects to the Workbench project files, and makes configuration changes to XML files where necessary.

To add subsystems to your Director EAR:

1. With your Director EAR project open in Workbench, select Project>Director EAR>Setup.

2. On the Setup Option panel of the EAR Setup Wizard, select Add.

   

3. On the Template Location panel, specify the directory for the template that contains the subsystems you want to add. Then click Next.

       For information about selecting templates, see Creating a new Director EAR project.

   

4. Click Yes to confirm your template choice.

   

   The wizard scans the template looking for subsystems that are not already in your Director EAR. If no new subsystems are found, the wizard lets you pick another template.

5. On the Subsystem Selection panel, select the subsystems you want to add.

   

   The Setup Wizard displays panels for configuration options.

6. Make configuration settings as appropriate.

   The procedure To create a new Director EAR project: has information about these panels (for example, see Content Management, Steps 13 and 14; WebDAV, Step 19).

7. On the last panel, check the summary information and clear the Build project after wizard is finished check box if you want.

8. Click Finish.

Just as with the wizard for creating the Director EAR, this wizard takes some time to copy subsystem files from the template to the project directory. Then it builds the project, if you selected that option. When it finishes, you're ready to continue work on your application.

Removing or disabling subsystems

The Director EAR Setup Wizard lets you remove or disable any installed subsystem.

Removing means the subsystem is removed from the project and references are removed from the project definition. Its files are deleted from disk.

Disabling means the subsystem files remain part of the project, but Workbench omits the subsystem from the archive when it builds the project. The subsystem files are still in the project and you can re-enable it when you want.

In both cases, references to the subsystem are removed from configuration files and classpaths in manifest files.

To remove subsystems in your Director EAR:

1. With your Director EAR open in Workbench, select Project>Director EAR>Setup.

2. On the Setup Option panel of the EAR Setup Wizard, select Modify.

   

3. On the Subsystem Setup panel, clear the Selected check box for a subsystem you want to remove. Click Yes when the wizard asks if you are sure, warning that its files will be deleted.

   NOTE   If you select a subsystem that another subsystem depends on, the wizard won't allow it to be deleted. A message tells you what subsystems depend on it.

   

   The wizard deletes the subsystem from the project and the subsystem files from disk.

4. Delete additional subsystems if you want, and click Finish when you are done.

To enable or disable subsystems:

1. With your Director EAR open in Workbench, select Project>Director EAR>Setup.

2. On the Setup Option panel of the EAR Setup Wizard, select Modify.

   The wizard displays the Subsystem Setup panel.

3. Disable a subsystem by clearing its Enabled check box. Then click Yes when the wizard asks if you are sure you want to disable the subsystem.

   

   The wizard deletes the subsystem from the project but leaves the files on disk so you can re-enable it later.

4. Enable a subsystem by selecting its Enabled check box.

   The wizard adds the subsystem back into the project.

5. Disable or enable additional subsystems if you want, and click Finish when you are done.

To find out what subsystems are enabled:

1. With your Director EAR project open in Workbench, select Project>Director EAR>Information.

   The Subsystem Information dialog displays the version and Enabled status of the subsystem in your project.

   

2. Click OK when you are done.

Adding a custom Web application to the EAR

When you run the Director EAR Wizard to create a new Director project, the wizard creates one custom Web application in the EAR. If you want to partition your application functionality into multiple WARs, you can use the Custom Web App Wizard to add additional modules.

Each custom Web application can include a resource set and a portal Web tier. If you include a resource set, subsystems that have a resource set binding—Rule, Security, and Workflow—are reset to point to the new resource set. After you use the wizard, you can reset subsystem bindings to other resource sets as needed.

Resource set restrictions    Before you decide to partition your application into many WARs, keep in mind Director restrictions for using the Rule, Workflow, and Security subsystems.

If you do have more than one Web application, you need to consider how you will use the rules, workflow, and security roles. Only one WAR can use rules; only one can use workflow; and only one can use security roles. The same WAR can use them all, or each subsystem can be bound to a different WAR.

You establish which WAR can use the subsystem's features by specifying a binding in the subsystem. The binding identifies the resource set that contains the application-defined definitions for that subsystem.

To add another custom Web application:

1. With your Director EAR open in Workbench, select File>New Project.

2. Select the Director tab, then choose Custom Web App and click OK.

3. Fill in the Custom Web App panel, described in Step 10 of the procedure To create a new Director EAR project:.

   

4. Click Finish.

   The wizard adds a new WAR to the project with the options you specified.

Editing the configuration of a resource set

Director provides a custom editor for editing the configuration file for a resource set. That file is always called resourceset.xml and is in the WEB-INF/conf directory of an application WAR that uses a resource set. This section describes interesting features of the editor.

NOTE    Configuring the resource set in Using the Resource Set in a Director Application provides information about the settings that you make in resourceset.xml.

To open the resource set editor:

1. On the Project tab of the Navigation Pane, find resourceset.xml in the WEB-INF/conf directory of the WAR.

   OR

   In the Relationship Viewer on the Resources tab of the Navigation Pane, find resourceset.xml in an appropriate view.

2. Double-click the file name.

   The editor opens and displays one of several tabbed panes. You can edit values in this Graphical View or you can select XML Source View and edit the XML as text.

   

Using boolean variables in check box fields

Variables you define in resourceset.xml are available for use in any attribute or element value. In Graphical View, you can choose variables from a list. The editor will display either a checked or an empty check box according to the current value of the variable.

To use a variable for a check box value:

1. Right-click on or beside the check box.

   A popup menu displays each boolean variable in normal and negated versions.

   

2. Select the variable you want from the list.

   The box is checked if the variable expression is true and empty if the variable expression is false.

NOTE   To see what values use variables, switch to XML Source View and look for variables in the form $variablename$ and !$variablename$.

Working with entries for resourcePath and libPath

When working with the list of entries for resourcePath and libPath, there are several points to keep in mind:

• For check box values, such as Enabled, you can use a variable. You might configure the resource set so that an entry is enabled when a variable is set to indicate the presence of a particular subsystem.

• The order of entries is significant. Use the Up and Down arrows to move entries to the correct position in the list. JARs and disk locations that you want searched first should be at the end of the list.

• To specify the location of a JAR that is in the deployed WAR, specify a relative path, usually WEB-INF/lib. You can use the variable $WEB-INF$, whose value is WEB-INF/lib.

• To specify a disk location, specify an absolute path. This is one of the few values that needs to be changed if you move the project to another computer. However, if you use the variable $WARLOCATION$ in the path, you will only need to redefine the variable, not all the entries, if you move the project.

Using resource set utilities

The resource set is not just a feature of your deployed application. It is also running in Workbench to enable tools like the Relationship Viewer and Search and to find resource files used by editors and wizards. To control the resource set in the Workbench, the editor provides several utilities on the General tab.

These utilities affect the resource set in Workbench only, not on the server where you deploy your application.

Core Development Guide

Copyright © 2002, SilverStream Software, Inc. All rights reserved.