Developing exteNd Director Applications
CHAPTER 2
This chapter explains how to create exteNd Director projects. It contains these sections:
Your work in exteNd Director is organized into projects. A project contains:
Information needed to deploy the application to a J2EE server
A set of JARs (the JARs included depend on your project configuration choices)
A project file has an .SPF extension. (A single SPF file can contain multiple components and resources of many different types.)
You can learn more about projects in general in the chapter on projects and archives in Utility Tools.
Default project When you install exteNd Director, a default project called Express Portal.spf is installed on your system and deployed to your server (for some installation types). This project is a complete, working application that you can use as a basis for building your own production portal. For more information, see the chapter on the Express Portal in the Portal Guide.
exteNd Director provides wizards that build different types of projects. Choosing the right project type includes decisions and knowledge about the:
exteNd Director supports two project types portlet applications and exteNd Director projects:
|
Choose this project type |
For this kind of application |
Deployment considerations |
|---|---|---|
|
Portlet application |
You have an existing portlet WAR and you want to use it with an exteNd Director portal. The Portlet Application Wizard adds exteNd Director's portlet runtime container to your portlet application. |
Supports shared, nonshared library, and 3rd party JARs environments. For shared library environments:
|
|
For nonshared library environments and 3rd party JARs environment: |
||
|
Project |
You want to create an exteNd Director project that includes: You use the Project Wizard to create:
This means you'll have to make some decisions during the project generation cycle, and there are multiple paths through this wizard based on the selections you make.
|
Supports shared, nonshared library, and 3rd party JARs environments. For shared library environments: |
|
|
|
For nonshared library and 3rd party JAR environments:
|
You can create a portlet application or an exteNd Director project:
To create a portlet application, see Configuring a portlet application project
To create an exteNd Director project, seeCreating an exteNd Director project
Using views to 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, or at system configuration and service settings. exteNd Director ships with several predefined views and also allows you to define custom views to display project items that are of particular interest to you.
For information on using views to find items in an exteNd Director project, see Working with Views.
To configure an existing portlet application to run with the exteNd Director portal:
Select the Director tab, choose Portlet Application, then click OK.
Continue as described in Specifying the existing Web App WAR next.
Click the ellipsis button and navigate to the disk location of the WAR that contains your portlets.
Click Next to go to the next wizard panel. See Specifying the project and archive name next.
To specify the project and archive name:
On the Project Information panel, specify the following options:
The wizard generates an exteNd Director–enabled Web application WAR.
At the top level of the WAR you'll see the standard J2EE WEB-INF/lib folder. In the WEB-INF folder you'll see these important files:
In the conf folder in the WEB-INF/lib folder, you'll see three important exteNd Director files:
Continue as described in Choosing the project template next.
To choose the project's template, complete the Project Template panel as follows:
Click Next to go to the next wizard panel. See Specifying project information next.
To specify project information:
Complete the Project Information panel as follows:
TIP: If you fill in the text boxes in order, subsequent text boxes are filled in automatically with useful default values.
|
Project setting |
What to specify |
|---|---|
|
Project Type |
Choose EAR or WAR. |
|
Project Name |
Specify the name you want to use for the project file (the .SPF extension is automatically appended). As you enter a project name, the archive name is filled in automatically. |
|
Project Location |
Specify a root directory for the project. The wizard copies template files and subdirectories to this location. You can type a path and/or use the Browse button to select a directory location. The location doesn't have to exist. As you enter a project location, the archive location is filled in automatically. If you do not specify an absolute path, the wizard uses exteNd Director's bin directory. |
|
Archive Name |
Specify the name of the archive file that will be generated. The .EAR or .WAR extension is automatically added, depending on the project type specified. 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 |
If your server supports J2EE 1.3, select J2EE 1.3; otherwise, select J2EE 1.2. NOTE: If you want to change the J2EE version of a project at a later time, see the chapter on how to handle J2EE versions in Utility Tools. |
If the directories you specified do not exist, the wizard offers to create each of them. Click Yes to confirm any new directories.
The next wizard panel displays. See Specifying the project setup next.
Complete the panel by choosing either Typical or Custom:
Click Next to go to the next wizard panel. See Specifying application options next.
To specify the application options:
On the Custom Web App panel, make these settings for the WAR and then click Next:
|
Custom WAR setting |
What to specify |
|---|---|
|
Create a Custom Web App now? |
(For EAR projects only). Select Yes to add custom Web application functionality. In an EAR project, the wizard includes a separate WAR project for the Web application. NOTE: Because exteNd Director requires a custom Web application for WAR projects, 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. |
|
Resources |
Select the component collections, tag libraries, and conditions and actions for rules you want to include in your application WAR. The list of available resources depends on the subsystem(s) you've selected. |
|
Template Resources Location |
A location for storing available resources that you can add to the project later. By default, this is the TemplateResources subdirectory. You can specify a different location; exteNd Director will copy available resources.
|
Click Next to go to the next wizard panel:
If your project includes the Content Management subsystem, see Specifying the Content Management Search configuration
Otherwise, see Directory configuration.
All exteNd Director projects are based on templates. A template is a collection of subsystems (which may have custom configurations) and application modules. Templates reside in a template directory on your file system, and the wizard copies files from the template to create your project. A template can include an exteNd Director project file (with the .SPF extension) for an exteNd Director EAR or WAR, but a project file is not required. If the template includes a project file, you can open the template project to add custom features to the template.
Template limitations You can use an existing exteNd Director EAR project as your template. 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 There are two installed templates:
The Content Management Search panel has three tabs: the Repository tab, the Synchronization tab, and the Filters tab.
To specify the Content Management Search configuration:
On the Repository tab, you can specify these settings:
On the Synchronization tab, you can specify these settings:
On the Filters tab, you can make this setting:
Click Next to go to the next wizard panel:
If you selected Typical setup, see Directory configuration.
If you selected Custom setup, see Content Management caching configuration next.
On the Content Management Caching Configuration panel, make the settings you want as follows:
Click Next to go to the next wizard panel. See Directory configuration next.
On the Directory Configuration panel, select a server-specific security realm.
The security realms are as follows:
TIP: If you have a user list from an earlier version of exteNd Director on the target server, select exteNd server (compatible).
Click Next to go to the next wizard panel:
If you chose an LDAP realm, you need to do more configuration; see LDAP realm configuration next.
Otherwise, see Framework configuration.
If you chose an LDAP realm, you need to specify your LDAP configuration options on the Directory Ldap Configuration panel.
LDAP configuration options are as follows:
To complete the Framework configuration:
On the Framework Configuration panel, specify values for these framework settings:
|
Framework option |
What to specify |
|---|---|
|
Director Framework Datasource |
Specify the JNDI name for your application's database. The database contains exteNd Director application data such as content and user information. The value you specify depends on the target application server. For exteNd Application Servers
For application servers other than the exteNd Application Server Replace the suggested value with the JNDI name for the database. For example: for a data source named MyDB, specify MyDB. For any application server Typically you will not need to access the JNDI name directly in your applications. But 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 DAC. The ID you specify must exist in the server's authentication realm when you deploy the exteNd 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 exteNd Director Admin elements.
|
|
Enable User Transaction Support? |
When checked, your application uses exteNd Director's transaction support. Uncheck this setting if you are deploying to an application server that does not provide JTA capabilities natively or through third-party extensions. |
Specify values for these cluster options:
|
Cluster option |
What to specify |
|---|---|
|
Do you want to use clustering? |
Select Yes to enable exteNd 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 exteNd Director Cache Coordinator.
NOTE: You must use the exteNd 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.
Specify a writable directory for exteNd Director use:
Click Next to go to the next wizard panel. See AES encryption key next.
exteNd Director encrypts portlet preferences in the database using a default key that is not unique. You can force the default key to be unique using the FIPS-approved AES encryption. If you require FIPS-compliant security for your application, it is recommended that you have your new projects generate a unique key.
On the AES Encryption Key panel, specify the following options:
|
Option |
Value |
|---|---|
|
Generate New AES encryption key? |
When checked, the wizard generates a unique encryption key for the stored portlet preferences. Checking this generates a new encryption key file. |
Click Next to go to the next wizard panel:
If you selected an EAR, see Namespace application next.
If you selected a WAR and an LDAP realm, see LDAP user options.
On the Namespace Application panel, you need to specify a namespace to be used in the URL for your exteNd Director application. The default is the project name. Namespacing allows you to deploy multiple exteNd Director EAR files to the same server when those applications have similar URLs and content. For example, if you deploy the DAC in several different EAR files to the same server, the application server will not be able to distinguish the different versions of the DAC unless EAR namespacing is enabled. If you won't have conflicting applications, you can disable namespacing so that your application's URL is shorter.
NOTE: EAR namespacing applies only to EAR projects. The Namespace Application panel is not displayed for WAR projects.
For more information about namespacing in an exteNd Director application, see EAR namespacing.
To complete the Namespace Application panel:
On the Namespace Application panel, enable namespacing by entering a namespace context and making sure the Yes check box is selected.
Click Next to go to the next wizard panel:
If you selected an LDAP realm, see LDAP user options next.
If your application does not include the WEBDAV, skip to Summary panel below.
Otherwise, see WebDav configuration.
If you selected an LDAP realm, you need to specify your user options on the User Ldap Options panel.
The LDAP user options are as follows:
IMPORTANT: Before you deploy a project that uses an LDAP realm, you need to perform these configuration steps:
You can perform these steps after you complete the EAR Wizard.
For details, see the section on LDAP predeployment tasks (eDirectory only).
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 exteNd Director application. You might change the default values to provide a shorter or application-related URL:
Click Next to go to the next wizard panel. See Summary panel next.
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 exteNd 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.
The Project Wizard generates a J2EE-compliant WAR or EAR depending on your selection.
At the top level of an exteNd Director WAR project, you will see several folders that contain JSP pages, HTML files, images, and other application resources. You will also see two standard J2EE folders—the WEB-INF folder and the META-INF folder:
Under the WEB-INF\lib folder, you will see:
A set of JARs needed by your application for either compile or runtime services (if they are grayed out in the display, that means they are needed for compile time only and are not deployed to the server)
ConfigService.JAR—contains the configuration files for each of the exteNd Director subsystems
An exteNd Director WAR project has a single WAR file associated with it; an exteNd Director EAR has several WAR files (Boot.war, Portal.war, and so on). Many of the WAR artifacts that are stored separately in an EAR project are merged together in a WAR project. For example, the WAR project contains a single WEB-INF\conf\config.xml file and a single WEB-INF\conf\services.xml file. Each of these files includes entries that are maintained separately in an EAR project. Similarly, a WAR project contains a single WEB-INF\web.xml file that includes entries for all Web tiers. In an EAR project, each Web tier has its own web.xml file with separate settings.
At the top level of an exteNd Director EAR project, you will see one or more service WARs (WARs that provide subsystem services). ContentMgmtService.war and WebDAVService.war are examples of service WARs:
Under the library folder you will see:
ConfigService.jar—A JAR containing configuration files for each of the exteNd Director subsystems included in the project
A set of JARs needed by your application for either compile or runtime services (in a shared library configuration, these service JAR files appear grayed out and in parentheses; they are available for compile-time use but are not included in the deployment archive)
Configuration and services files Each subsystem within an exteNd Director EAR project relies on a configuration file and a services file:
EAR namespacing The J2EE specification does not require the EAR name to be part of the context for a WAR file. This can be problematic when multiple EAR files with similar content are deployed to the same server. For example: if you deploy the DAC in several different EAR files to the same server, the application server will not be able to distinguish the different versions of the DAC. To solve this problem, exteNd Director introduces the notion of EAR namespacing. The namespace is part of the URL for accessing the exteNd Director Web tiers and custom Web applications.
When you run the Project Wizard in exteNd Director, you can specify that EAR namespacing be enabled for an EAR project. To implement namespacing, exteNd Director prefaces the context for each WAR with the namespace you specify. The context for each WAR is specified in the application.xml file for the EAR. The Project Wizard uses the name assigned to the EAR as the default namespace.
For example, suppose you enable namespacing for an EAR and specify a namespace of MyEAR. Each module section in application.xml has a context-root element that prepends the namespace to the WAR name. The module section for the Content Management subsystem would look like this:
<module> <web> <web-uri>ContentMgmtService.war</web-uri> <context-root>/MyEAR/ContentMgmtService</context-root> </web> </module>
Other subsystems would have similar context-root entries.
NOTE: On a Novell exteNd Application Server: if you deploy to a database other than SilverMaster, the URL would also include the database name.
Classloading within an exteNd Director EAR A WAR file can access classes in a JAR file that is contained within that WAR, as well as classes in a JAR file that is placed outside the WAR in some other location within the EAR. exteNd Director applications take advantage of both of these configurations.
Classpath for WAR When a WAR file uses the services of a JAR file within the WAR, the classes in the WAR have no difficulty locating the classes in the JAR—since these classes are automatically included in the WAR's classloading environment. However, when a WAR file uses the services of a JAR file that is located outside the WAR, the JAR must be added to the classpath for the WAR. J2EE applications do this by setting the classpath in the MANIFEST.MF file in the META-INF directory within the WAR.
Classpath for Framework exteNd Director applications also maintain a simulated classpath for the Framework, which allows the classes in the Framework to find classes in the other subsystem JAR files that have been included with a particular exteNd Director EAR configuration.
Each exteNd Director subsystem has one or more archive files associated with it. When you select a subsystem in the Project Wizard, the wizard adds the archives you need for the project type you're creating (EAR or WAR). In addition, the wizard automatically enforces any dependencies that exist for the subsystem. If for example you include a subsystem that depends on others, those other subsystems are also included in your project.
The subsystem archive files conform to the following naming convention:
Often a subsystem will be deployed in its entirety. However, exteNd Director allows you to deploy the archive files separately. For example, you might deploy the UserService.jar file without including the UserTag.jar, UserEjb.jar, and UserClient.jar files.
The following table shows the archive files for each exteNd Director subsystem or service:
*Uses PortletImpl.jar and PortletAPI.jar
The following table outlines the interdependencies among the exteNd Director subsystems:
Several additional third-party archive files are required for the successful execution of exteNd Director applications. In a nonshared library environment, these modules are delivered in the /library directory of an exteNd Director EAR project (the WEB-INF\lib directory of a WAR project). Most manifest files (META-INF\MANIFEST.MF) have these modules listed as dependencies.
The Project Wizard and Setup Wizard enforce these dependencies for nonshared library environments. If you include a subsystem that depends on others, those other subsystems are also included in your project. If you try to remove a subsystem that others depend on, the Setup Wizard forces you to remove the dependent subsystems first before you can remove the subsystem they depend on. In a shared library environment, the wizard cannot enforce any dependencies.
Copyright © 2003 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved. more ...
