|
|
Core Development Guide |
This chapter explains how to use Director wizards in the Novell exteNd Workbench to create and configure Director applications. It contains the following sections:
A Director application is packaged in a single Director EAR or Director WAR file. You can create the EAR or WAR by running the Director Project 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 a 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 project. You can also add or remove subsystems or make any other necessary changes to the structure and content of the EAR or WAR, 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 or WAR to one or more servers.
Basic steps Here are the general steps you need to follow to configure a Director application:
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 or WAR projects.
For installation instructions, see the Release Notes.
If you will use the Search subsystem, configure the Autonomy DRE.
For instructions, see the Search Guide.
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 an exteNd application server, this can be different from the deployment database. A typical scenario is to deploy the Director application to the SilverMaster database with a separate database for Director data.
For instructions, see your DBMS documentation.
Create a new Director EAR or WAR project using the Director Project Wizard with a Director template.
For instructions, see
Creating a new Director project.
Set up dynamic loading so that you can test application resources without frequent redeployments.
For instructions, see
Dynamic loading of resources and classes.
Do the required deployment setup for your server. Some setup is done in Workbench; for the rest, you use your server's tools.
Deploy the application to provide access to Web-tier Director tools.
For instructions, see
Deploying a Director Application.
You create a new Director project with the Director Project Wizard, which is available in exteNd Workbench after you've installed Director. The Director Project 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 or WAR, 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 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:
Typical setup from the Director template also provides the following Web tiers:
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 project:
In exteNd Workbench, select File>New Project.
The New Project dialog appears.
Select the Director tab, then choose Director Project and click OK.
On the Template Location panel in the Director Project Wizard, specify the full path for a directory that contains the template you want to use. You can specify one of the following:
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.
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.
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.
A filled-in panel might look like this:
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.
Click Yes to confirm each new directory.
The wizard displays the Setup Type panel.
You have a choice of these setup types:
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.
On the Subsystem Selection pane, select the subsystems you want then click Next.
For descriptions of the Director subsystems, see
About Novell 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.
NOTE: The following subsystems are required for a WAR project: Framework, Directory, Portal, User, and Security.
The wizard displays the Custom Web App panel, where you specify options for the WAR that will contain your application code.
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 custom Web application functionality. In an EAR project, the wizard includes a separate WAR project for the Web application. If you select No, you can add one later with the Custom Web App Wizard (described in Adding a custom Web application to the project). NOTE: For WAR projects, Director requires a custom Web application. Therefore, this option is not available when you're creating a WAR project. |
|
Name |
The context name for the WAR. This is used in URLs for pages of your application. NOTE: For WAR projects, the context name for the WAR is the same as the Project Name specified on the Project Information panel. This option is not editable when you're creating a WAR project. |
|
Type |
In an EAR project, select Resource Set 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. NOTE: For WAR projects, Director requires a custom Web application that includes a resource set and a portal. Therefore, the Resource Set and Portal check boxes are grayed out for WAR projects.
|
|
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.
|
|
Template Resources Location |
A location for storing available resources 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.
NOTE: EAR namespacing applies only to EAR projects. The Namespace Application panel is not displayed for WAR projects.
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.
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.
On the Repository tab, you can make these settings:
On the Synchronization tab you can make these settings:
On the Filters tab you can make these settings:
Then click Next.
If you selected Typical setup, skip to Step 15 for the Directory Configuration panel.
On the Content Management Caching Configuration panel, make the settings you want, and click Next.
The wizard displays the Directory Configuration panel.
On the Directory Configuration panel, select a server-specific security realm. Then click Next.
The security realms are described below:
Select SilverStream (compatible) if you have a user list from a previous version of Director on the target server.
If you select an LDAP realm, you need to specify your LDAP configuration options on the Directory Ldap Configuration panel.
The LDAP configuration options are described below:
When you click Next, the wizard displays the Framework Configuration panel.
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 an exteNd application server, the JNDI name includes qualifiers around the database name, like this: 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 TIP: Typically you will not need to access the JNDI name directly in your applications. However if you need to do so, you can use the framework API to get the property stored in the FrameworkService config.xml, as shown in this coding technique: // get an EbiConfig object
com.sssw.fw.api.EbiConfig myconfig = com.sssw.fw.factory.EboFactory.getConfig();
// get value from the key in config.xml
String dsname = myconfig.getProperty("com.sssw.fw.datasource.jndi-name");
// access the data source
try{
javax.naming.InitialContext ctx = new javax.naming.InitialContext();
javax.sql.DataSource source = (javax.sql.DataSource)ctx.lookup(dsname);
}
catch(javax.naming.NamingException ne){}
|
|
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 authentication realm when you deploy the Director EAR or WAR. NOTE: If you do not want to use ACL-based security in your application, set the Locksmith to anonymous to prevent ACLs from being set up for the Director Admin elements.
|
Specify values for these cluster options:
The Generated UID field displays an application identifier used for clustering. You cannot change it.
Specify a writable directory for Director use:
Then click Next.
If you selected Typical setup, skip to Step 22 and the Summary panel. If you selected Custom setup and included the WebDAV subsystem, the wizard displays the WebDAV Configuration panel next.
If you selected an LDAP realm, you need to specify your user options on the User Ldap Options panel.
The user options are described below:
NOTE: Before you deploy a project that uses an LDAP realm, you need to perform some additional configuration steps.
For more information, see Configuring an LDAP Realm.
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.
Then click Next.
The wizard summarizes the project details.
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.
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.
There are several ways you can change your Director EAR or WAR. 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
After you've created a Director project, configuration settings for various subsystems are stored in the subsystem's config.xml. You can change configuration settings you made in the Director Project Wizard using the Director Configuration tool or by editing the config.xml file. 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 Project 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 an EAR project can use rules; likewise for workflow and security roles.
To change configuration settings using a wizard:
With your Director project open in Workbench, select Project>Director Project>Configuration.
In the Director Project Configuration dialog, click the tab for the subsystem whose settings you want to change.
To change configuration settings by editing the config.xml file directly:
With your Director project open in Workbench, go to the Project tab and locate the config.xml file.
TIP: The config.xml file is typically located in the subsystem-name-conf subdirectory of the subsystem-nameService.jar file for the subsystem. For example, the Directory subsystem has a config.xml file in the DirectoryService- conf subdirectory of the DirectoryService.jar file. In the case of the Web tiers, the config.xml is located in the conf subdirectory of WEB-INF.
For more information about where project files are located, see
Director project structure.
Director provides a standard Key/Value editor for config.xml files.
You can edit the XML source view if you prefer.
NOTE: The XML source view does not include multiple-line comments in some versions of Workbench. You can open the XML file in a text editor to be sure that you see the complete source.
To change configuration settings using a predefined view:
With your Director project open in Workbench, go to the View tab within the Resources tab and select settings.ear.xml.
NOTE: The settings.ear.xml view lets you find configuration settings in an EAR project. In a WAR project, you need to use the settings.war.xml view.
The settings view includes a folder containing the configuration files for all subsystems. For example, open the Directory Service folder and select the config file.
After you have created a Director project, you can use the Director Project 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 project. Another template might include a subsystem that your original template didn't have. The Setup Wizard copies subsystem files to the project directory, adds subprojects to the Workbench project files, and makes configuration changes to XML files where necessary.
To add subsystems to your Director project:
With your Director project open in Workbench, select Project>Director Project>Setup.
On the Setup Option panel of the Setup Wizard, select Add.
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 project.
Click Yes to confirm your template choice.
The wizard scans the template looking for subsystems that are not already in your Director project. If no new subsystems are found, the wizard lets you pick another template.
On the Subsystem Selection panel, select the subsystems you want to add.
The Setup Wizard displays panels for configuration options.
Make configuration settings as appropriate.
The procedure To create a new Director project: has information about these panels (for example: see Content Management, Step 13 and Step 14; WebDAV, Step 21).
On the last panel, check the summary information and clear the Build project after wizard is finished check box if you want.
Just as with the wizard for creating the Director project, 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.
The Director Project 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 project:
With your Director project open in Workbench, select Project>Director Project>Setup.
On the Setup Option panel of the Setup Wizard, select Modify.
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.
Delete additional subsystems if you want, and click Finish when you are done.
To enable or disable subsystems:
With your Director project open in Workbench, select Project>Director Project>Setup.
On the Setup Option panel of the Setup Wizard, select Modify.
The wizard displays the Subsystem Setup panel.
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 reenable it later.
Enable a subsystem by selecting its Enabled check box.
The wizard adds the subsystem back into the project.
Disable or enable additional subsystems if you want, and click Finish when you are done.
To find out what subsystems are enabled:
With your Director project open in Workbench, select Project>Director Project>Information.
The Subsystem Information dialog displays the version and Enabled status of the subsystem in your project.
When you run the Director Project Wizard to create a new EAR 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:
With your Director project open in Workbench, select File>New Project.
Select the Director tab, then choose Custom Web App and click OK.
Fill in the Custom Web App panel, described in Step 10 of the procedure To create a new Director project:.
The wizard adds a new WAR to the project with the options you specified.
The Director Project Setup Wizard provides a way to update your project files. It compares the files in a template (normally the template from which the project was created) to the files in your project directory and copies all files that are not present or have changed.
NOTE: This update utility does not analyze how your project is configured. It copies files from subsystems that your project does not include.
To update your Director project:
With your Director project open in Workbench, select Project>Director Project>Setup.
On the Setup Option panel of the Setup Wizard, select Update.
The Update Your Director Project Wizard appears.
In the From location: box, enter the location of the source project, typically the standard EAR template in your Director installation. For example:
C:\SilverStream\eXtendDirector\templates\Director
In the To location: box, enter the location of the root of your target EAR project, for example:
C:\Director_Projects\My_Project
|
Mode |
What it means |
|---|---|
|
All |
Update all files (no filtering) |
|
Classes |
Update .class files only (intended for updating subsystem classes in the library WAR) |
|
Selective |
See Step 7 (next) |
If you choose Selective, specify lists of extensions in the Include Extensions and/or Exclude Extensions fields. Separate extensions by semicolons.
Check Check date & length to replace files that have a different length in addition to those that have a different date.
Check Copy new files to include new files in addition to updated files. Any file that exist in the From location but not in the To location is considered to be a new file. This option is required for version updates.
Check Trial to see a list of the files to be replaced or copied without actually performing the update.
Check the Release Notes associated with the source template for files that require a manual update.
NOTE: If you want to change the J2EE version of your project to match the update, see "How to Handle J2EE Versions" in the Workbench Getting Started guide.
To update an individual Web application:
In the Update facility, enter the location of the Web application template directory in the From location: box, for example
C:\SilverStream\eXtendDirector\templates\Director\Portal
Enter the location of your Web application in the To location: box, for example
C:\Director_Projects\My_Project\My_Portal
Repeat this step for each Web application in your project that is not named Portal.
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: The section Configuring the resource set provides information about the settings you make in resourceset.xml.
To open the resource set editor:
On the Project tab of the Navigation Pane, find resourceset.xml in the WEB-INF/conf directory of the WAR.
OR
In the View tab within the Resources tab of the Navigation Pane, find resourceset.xml in an appropriate view.
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.
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:
Right-click on or beside the check box.
A popup menu displays each boolean variable in normal and negated versions.
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$.
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.
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.
|
Button |
What it does |
|---|---|
|
Stop, Start, Restart |
Starts or stops the resource set. Use Restart after changing entries on resourcePath and libPath so Workbench finds the correct resource set contents. Use Stop to conserve memory when you're not editing a resource set's files or using it on the Resources tab of the Navigation Pane. |
|
Validate |
Runs the validation classes in the resource set. The default validation verifies that entries in libPath and resourcePath exist. If you've added your own validation classes, they are executed too.
If you set Validate to true in resourceset.xml (on the upper half of the General tab), the same validation process is run during the Director boot process on the server. |
|
Clear |
Clears the messages reported by resource set utilities. |
|
Enable/Disable Resource Subprojects |
Displays a list of resource JAR subprojects in the resource set. Clear the check boxes of projects whose JARs you want to leave out of the archive. The settings you specify will be used the next time you build the archive in Workbench. When dynamic class loading is enabled, you need to disable subprojects whose classes will be loaded from a disk location. Typically this is the myapp-resource subproject. To find out what is being loaded from disk, see the last entries on the libPath tab. You might also disable subprojects that your application isn't using yet to speed deployment. |
|
|
Core Development Guide |
Copyright © 2000, 2001, 2002, 2003 SilverStream Software, LLC, a wholly owned subsidiary of Novell, Inc. All rights reserved.
