Tools Guide

Chapter 8 JAR Designer

The SilverStream JAR Designer lets you perform all of the tasks associated with creating and maintaining JAR files. It also enables you to perform all of the application assembly associated with Enterprise JavaBeans.

This chapter describes how to use the SilverStream JAR Designer. It includes these sections:

For background information about JAR files, see the chapter on utility classes, JAR files, and JavaBeans in the Programmer's Guide.

About the JAR Designer

SilverStream's JAR Designer allows you to

Create standard JAR files that you can use to encapsulate and deliver the components of a SilverStream application
Create EJB JAR files. The JAR Designer provides a graphical interface that helps you create an EJB1.1-compliant deployment descriptor
Create and modify manifest files for an existing JAR or EJB JAR file
Import JAR files (including EJB JARs) and ZIP files created using non-SilverStream tools
Import and manage other types of media, like graphics and sound files

When to use JAR files In SilverStream, the following components must reside in a JAR:

JavaBeans
Enterprise JavaBeans
Java Server Pages

In addition, if you want to access a class that resides in a different database, you must place that class in a JAR file.

About the JAR Designer interface

The JAR Designer interface differs depending on how you invoke it.

Using Upload Media Item If you invoke the JAR Designer by choosing Upload Media Item, SilverStream displays a dialog that prompts you to specify the file to upload. It looks like this:

Using Upload JAR, ZIP, or EJB If you invoke the JAR Designer by choosing Upload JAR, ZIP, or EJB, SilverStream displays a dialog which prompts you to specify the item to upload. It looks like this:

Using Create JAR If you invoke the JAR Designer by choosing Create JAR, the JAR Designer consists of a single tabbed pane where you can add and remove the contents of the JAR file as shown below.

Using Create EJB JAR If you invoke the JAR Designer by choosing Create EJB JAR, then the JAR Designer consists of two panes: one to manipulate the contents of the JAR file and the other to create the EJB Deployment Descriptor as shown here:

Creating JAR files

To create a JAR file in the SilverStream Designer:

Click the EJB Jars and Media icon in the left pane.
Click on the New button in the right pane and click Create JAR or Create EJB JAR. The JAR Designer appears.
From the JAR Contents tab, select a SilverStream component (for example, page, form, or object or JavaBean) to include in the JAR file.
Double-click the object or click the > button to add the selected component to the JAR file list. Repeat this step for each component you want to add to the list.
After you have added all of the components to the JAR file, save it.

Once you have saved and named the JAR file, SilverStream creates the JAR file in the current database.

Editing JAR files

You might need to edit a JAR file when you want to add or remove items.

To edit JAR files:

Click the EJB Jars and Media icon in the left pane.
Expand the Jars object in the right pane to display the available JAR files.
Double-click the JAR file you want to edit. The JAR Designer appears.
From within the JAR Designer, click the objects you want to add to your JAR in the left pane of the JAR Editor. Click the > button to add them to your JAR file.
Click on objects you want to remove from your JAR in the right pane of the JAR Editor. Click the < button to remove them from your JAR file.
When you have modified the file as needed, save it.

NOTE You cannot edit imported JAR files; only JAR files created using the SilverStream JAR Designer can be edited.

Rebuilding JAR files

You need to rebuild a JAR file when you have made changes to any of the components in the JAR.

You cannot use Rebuild to:

Change the list of items in the JAR file
Rebuild JAR files that you imported into the SilverStream environment.

How JARs are rebuilt When you rebuild a JAR file, SilverStream performs the following process:

SilverStream reads the contents of the JAR.
It checks the date of each object in the JAR file against the date of the corresponding object on the server
If the version of the object on the server is newer, SilverStream copies that newer version into the JAR file.

For individual items, such as Forms/form1 or Views/view1, the newer versions of these items (if any) replace the existing ones.

For directories, such as Forms, Views, and so on, only the items that were in those directories at the time of the JAR's creation, will be reinserted.

Packages, however, are dynamically regenerated each time you rebuild. For example, if the user adds any new classes or subpackages to a package, they will get inserted into the JAR, newer versions of existing classes will be substituted for older ones, and any deletions will be reflected in warning messages.

If you have created new packages that are not subpackages of packages already included in your JAR file (for example you created some new utility classes), you must manually add these to your JAR file. See Editing JAR files.

To rebuild JAR files in the Designer:

Choose the EJB Jars & Media icon in the left pane.
Expand the Jars object in the right pane to display available JAR files.
Right-click on the JAR file you want to update.
Select Rebuild from the popup menu. SilverStream updates all of the files in the JAR file.

NOTE You cannot rebuild imported JAR files; only JAR files created using the SilverStream JAR Designer can be rebuilt.

You can also rebuild a JAR using the SilverCmd command line tool.

For more information, see the chapter on SilverCmd in the Facilities Guide of the server's Core Help.

Publishing JAR files

When you create or rebuild a JAR file, it is available only on the server in which it is created or rebuilt. To make the contents of a JAR file available on another server you need to publish the JAR file. This copies the JAR file from the source database to the destination database on the server.

To publish a JAR file:

Choose the Publish icon in the Designer icon bar. The Publish Wizard appears.
Choose the source and destination databases in the Publish Wizard and click Next.
Expand the EJB Jars & Media objects in the left pane to display available JAR files.
Click the JAR file you want to publish then double-click the file or click the > button to add the selected file to the Destination pane.
Click Finish to copy the JAR file to the destination database.

Exporting JAR files

To make your JAR file available to someone outside of your SilverStream environment, you need to export the file (save the file to disk) and then use some means such as e-mail, ftp or network copying, to move the file to where it is to be used.

NOTE If you put forms or views into JARs, they will not work outside of the SilverStream environment. They rely on the metadata description stored external to the class files.

To export a JAR file:

Choose the EJB Jars and Media icon in the left pane.
Expand the Jars object in the right pane to display available JAR files.
Right-click on the JAR file you want to export. A popup menu appears.
Select Save to Disk in the popup menu. The Save Media File dialog appears.
Select the directory, type the name of the JAR file, including the .jar extension, into the filename box, and click Open.

You can also export a JAR using the SilverCmd command line tool.

For more information, see the chapter on SilverCmd in the Facilities Guide of the server's Core Help.

Importing JAR files

You can use JAR files created outside of your SilverStream environment by uploading them into the JAR Files directory in your SilverStream database.

To import a JAR file that does not include references to files in other JARs:

Make sure the JAR file is on a disk that is accessible from the SilverStream Designer.
Click on your database EJB Jars & Media icon in the left pane of the Designer window.
Click on the New button and select Upload JAR, Zip or EJB. The Open Media File dialog appears.
Select the JAR file you want to import, and press Open.

SilverStream copies the file into the JARs directory of the current database.

You cannot modify imported JARs using the SilverStream Jar Designer. You must make any modifications to the JAR file before importing it into SilverStream.

For more information on importing JAR files using SilverCmd, see the chapter on SilverCmd in the Facilities Guide of the server's Core Help.

To import a JAR file that includes references to files in other JARs and a Class-path entry in the manifest file:

If the JAR file already contains a Class-path entry in the manifest file:

Import the JARs containing the referenced files (the referenced JARs).
Import the primary JAR.
NOTE Add the primary JAR to the Uses Jar Files... list of any forms, pages, business objects, or deployment plans that access the primary JAR (accessed via the File>Jar files menu item described in the section To make JAR files available to deployment plans, forms, pages, and business objects:.

To import a JAR file that includes references to files in other JARs and no Class-path entry in the manifest file:

If the JAR file does not contain a Class-path entry in the manifest file:

Extract the manifest of the primary JAR (making sure that the path on extract matches the manifest's path within the JAR).
Add the Class-path attribute to the manifest of the primary JAR.

See the following section for information on setting the Class-path attribute.
Update the primary JAR with the new manifest file.
Follow the steps (above) that describe how to import the JAR file that already contains the Class-path entry.

Creating Manifest files

A manifest file can contain an entry, called a section in the Manifest file specification, for each of the files contained in the JAR. You might think of the Manifest file as a table of contents (with attributes) for the JAR. You are not required to include all of the files that do reside in the JAR in the manifest file. A JAR file that contains JavaBeans requires a manifest file, and all of the JavaBeans must be listed.

Both standard and EJB JAR files require a manifest file when they include references to classes that reside in other JAR files.

To create a Manifest file (JARs created in SilverStream only):

Open the JAR file.
Open the Property Inspector for the JAR and check the Include Manifest checkbox.

SilverStream adds a Manifest file tab which has two modes List View (the default) and Text View. You can go back and forth between modes. SilverStream will attempt to convert the entries made in Text mode to the appropriate values in List Mode.

To add entries in List View mode:

Choose the plus icon from the toolbar.

SilverStream displays the Manifest Entry dialog.
Enter the name or the manifest entry.

This name is a relative path to the object that you are adding to the Manifest file. It must use forward slashes. For example, com/myco/MyClass.class.
Choose OK.

The Property Inspector displays a new tab called Manifest.
If the class is a JavaBean, choose the Java-Bean check box.

SilverStream adds the Java-Bean: True entry to the manifest file.
To specify additional attributes, choose Add New Attribute and enter the name/value pairs in the text boxes provided.

Some examples of additional attribute names for JavaBeans include: depends-on, or design-time-only.
When you are done, close the Property Inspector and save the JAR file.

Upon Save, SilverStream analyzes the Manifest file. If there are errors, they are displayed in a dialog.

To add/remove entries in Text View mode:

Choose the Text View radio button.
The Text View mode is a freeform text editor. You must type the entries as required by the manifest file specification.
When you are done, save the JAR.

Accessing classes in other JAR files

Sometimes the classes in a JAR file include references to classes that reside in one (or more) other JAR files. In these situations, you must provide a Class-path entry in the manifest file of the primary JAR. This Class-path entry lists the JARs containing the referenced classes.

Here's how it works:

In the the primary JAR (the one that contains external references), create a manifest file. The manifest file must include a Class-path entry that contains the name of each of the referenced JAR files.

The Class-path entry in the manifest file is required regardless of the tool used to create the JAR file.
Specify the name of the primary JAR in each deployment plan, form, page, or business object using the File>JAR files menu item described later.

For example, suppose that you have a JAR file (JAR1) that contains classes that are needed for your form or business object. One of the classes in JAR1 refers to a class in JAR2 and a class in JAR3. JAR1, the primary JAR, must contain a manifest file and it must include a Class-path entry that lists both JAR2 and JAR3.

Now suppose that JAR1 refers to a class in JAR2. Also suppose that the class in JAR2 refers to a class in JAR3. In this case, JAR1's Class-path entry in the manifest file would only list JAR2. JAR2 would also need a manifest file with a Class-path entry. JAR2's Class-path entry would list JAR3.

Any form, page, business object, or deployment plan that uses classes in JAR1 must include a reference to JAR1 in it's Uses Jars list. You do not need to include JAR 2 or JAR3 in either example described above. (You populate the Uses Jars list using the File>Jar files menu item, described later.)

To create a Class-path entry in a manifest file:

Open the JAR.
If a Manifest tab does not exist, create one by choosing Properties then choosing the Includes Manifest check box.

The JAR Designer adds a Manifest tab.
Access the manifest tab.
Choose the Text View radio button (shown at the bottom of the Manifest tab).
Position your cursor at the end of the first line (directly after Manifest-Version: 1.0), and press Enter. (Make sure there are no extra spaces between the 1.0 and the carriage-return.)
Add this to the line:
```
  Class-path:
```
This is a key word which must be spelled exactly as shown (as specified in Sun's Manifest specification).
Add the names of the referenced JARs in a space-separated list on the same line as the Class-path: keyword.
NOTE Make sure that there is a blank line between this section of the manifest file and any file entries that might occur below it.
Save the JAR file.

Usage tips

The list of referenced JARs is not case-sensitive.
Do include the .jar extension in the name.
The list of referenced JARs cannot include any path specifications. It is a list of JAR names only.
If the referenced JAR resides in another database, use this syntax to specify its name:
```
  db:jarName.jar
```
The referenced JARs must reside on the SilverStream server before you can use any of its components.

To make JAR files available to deployment plans, forms, pages, and business objects:

As long as the primary JAR contains a Class-path entry for any JARs containing referenced files, you only have to specify the name of the primary JAR file in the Uses Jars list of the deployment plan, a business object, a page, or a form.

From the Deployment Plan, Page, Form or Business Object Designer main window, choose File>Jar files
Choose the referenced JARs from the dialog and add them to the list.
Choose OK.

Defining an EJB Deployment Descriptor

The EJB JAR file is the deployment vehicle for Enterprise JavaBeans. The EJB JAR includes one or more EJB Java class files, their home and remote interfaces, and a deployment descriptor.

The deployment descriptor is an XML description of the contents of the EJB JAR. It initially contains information that a bean developer provides about the constituent beans. By the time the EJB JAR is deployed, it will contain all of the information that the EJB deployer and the EJB container need to create the proper runtime environment for the Enterprise JavaBeans it contains. The EJB specification defines the structure of the deployment descriptor as an XML file with its own DTD.

The deployment descriptor contents consist of two parts:

A description of the individual beans in the JAR (defined by the bean developer). The first part of the deployment descriptor provides information about the individual beans in the EJB JARs, such as the name of the EJB's Java class file, the name of it's home and remote interfaces. This part of the deployment descriptor is required. It is written by the bean provider.
The runtime attributes of the beans in the JAR (defined by the application assembler). The second part of the deployment descriptor includes information about the runtime attributes of the beans in the EJB JAR, such as entries that name roles, method permissions, and transaction attributes. The deployer then uses this combination of information to install the EJB JAR on the target server and to map this information to actual entities in the runtime environment. This information is optional until the beans are assembled into an application. An EJB JAR can be deployed and enabled without this part of the deployment descriptor.

SilverStream implements this structure within the JAR Designer by including an Enterprise JavaBeans section and an Application Assembly section in the descriptor tab as shown here:

You can populate the deployment descriptor in one of these modes:

XML View. Edits the contents as XML.
List View. Edits the contents by adding nodes and specifying their properties graphically.

Describing beans

The tasks described in this section relate to the components in the Enterprise JavaBeans section of the deployment descriptor using List View mode. (The Enterprise JavaBeans section is represented as the <enterprise-beans> node in XML.)

To add an EJB to the deployment descriptor:

Open the EJB JAR and access the Descriptor tab.

You must have already created an EJB JAR and added the packages or objects to the JAR.
Highlight the Enterprise JavaBeans icon, right-click and choose Add Session Bean or Add Entity bean.

SilverStream creates an entry called UntitledSessionBean or UntitledEntityBean.
Highlight the Untitled bean entry and open the Property Inspector.
Provide the necessary values and close the Property Inspector.

The Property Inspector includes required and optional entries. The properties vary depending on the entry.

Understanding bean properties The deployment descriptor requires these entries for each EJB regardless of its type:

JAR Designer property name	XML tag	Description
Bean name	<ejb-name>	Used to differentiate this bean from others in the EJB JAR.
Bean class	<ejb-class>	The name of the class that implements the bean.
Home interface name	<home>	The name of the bean's home interface class.
Remote interface name	<remote>	The name of the bean's remote interface class.
Description	<description>	A textual description of the bean. You can provide any information that might be useful for application assemblers or deployers.

Session beans also require the following additional information

JAR Designer property name	XML tag	Description
State management type	<session-type>	Specifies whether the bean is a stateful or stateless session bean.
Transaction type	<transaction-type>	Specifies who manages the bean's transactions; the bean or the container.

Entity beans require this additional information:

JAR Designer property name	XML tag	Description
Primary key class name	<prim-key-class>	The name of the bean's primary key class.
Primary key field	<prim-key-field>	The primkey-field element is used with CMP beans. It specifies the name of the primary key field, that is, the field in the entity bean class that contains the primary key. (This is optional.)
Persistence type	<persistence-type>	Specifies who manages the bean's persistence; the bean or the container.
Reentrant	<reentrant>	Specifies whether or not the bean is reentrant.
Persistent fields	<cmp-field> <field-name> </cmp-field>	The list of persistent fields that the container must load and store. (Optional for BMP beans.)

To add a primary key field:

You can only specify a primary key field for entity beans using container-managed persistence.

Add an entity bean to the deployment descriptor as described in To add an EJB to the deployment descriptor:.
Provide values for the bean name, bean class, home interface class and remote interface class properties.
Set the persistence type property to container-managed. (This enables the Primary key field property.)
Specify the Java data type in the Primary key class property.

This must be a Java base class type like java.lang.Integer or java.lang.String.
Specify the Primary key field by either of the following:
- Choosing the ellipsis button and then choosing the persistent field from dialog
- Typing the name of the persistent field

To add an environment property:

Highlight the Environment icon, right-click and choose Add Environment entry.

SilverStream creates an entry called UntitledEnvironmentProperty.
Highlight the UntitledEnvironmentProperty, right-click and choose Properties.

SilverStream launches the Property Inspector.
Specify values for the properties and close the Property Inspector when complete.

Understanding environment properties Environment properties allow the application assembler or deployer to map static data or variables to values that are meaningful to the operational environment. The bean developer must add entries and optionally initial values for each environment property that the bean references. The entries are added to the <env-entry> node of the deployment descriptor. They include:

JAR Designer property name	XML tag	Description
Name	<env-entry-name>	The name of the environment property. It is a required entry. It must exactly match the environment variable specified in the code. This is the name that is registered with JNDI and the name that the bean should reference. This allows you to substitute values for a variable instead of hardcoding values.
Value	<env-entry-value>	The entry's value.
Entry type	<env-entry-type>	The entry's data type.
Description	<description>	A textual description that allows you to communicate any special information to the application assembler, bean deployer, or administrator.

At deployment time, SilverStream registers the environment property with JNDI so it can be located by the bean at runtime.

For an example of how environment properties are used, see the EJB part of the online Application Techniques.

To add a bean reference:

Highlight the Environment icon, right-click and choose Add Bean Reference.

SilverStream creates an entry called UntitledBeanReference.
Highlight the UntitledBeanReference, right-click and choose Properties.

SilverStream launches the Property Inspector.

You can choose the ellipses (...) button next to the Referenced bean text field. Choose the appropriate bean from the list in the dialog and choose OK. SilverStream can then insert the remaining information about the bean such as its home and remote interface classes.
Specify values for the properties and close the Property Inspector when complete.

NOTE SilverStream requires that referenced beans reside in the same EJB JAR file. To reference a bean located in a different EJB JAR, you can create a composite EJB JAR. For more information, see Creating composite EJB JARs.

Understanding bean references Bean references allow one or more EJBs to find the home object of other EJBs using a logical reference instead of an actual (and possibly not known) JNDI name. The bean developer must add entries for each of the EJB home objects that a bean references in the <ejb-ref> node of the deployment descriptor

JAR Designer property name	XML tag	Description
Bean name	<ejb-ref-name>	The name of the referenced bean as it is looked up by referring beans. The name of the bean reference in the java code. Required. This must exactly match the bean reference as specified in the code.
Referenced bean name	<ejb-link>	The referenced bean's class name.
Bean type	<ejb-ref-type>	The referenced bean's type (entity or session).
Home interface	<home>	The referenced bean's fully qualified home interface name.
Remote interface	<remote>	The referenced bean's fully qualified remote interface name.

For an example of how bean references are used, see the EJB section of the online Application Techniques.

To add a role reference:

Highlight the Environment icon, right-click and choose Add Role Reference.

SilverStream creates an entry called UntitledRoleReference.
Highlight the UntitledRoleReference, right-click and choose Properties.

SilverStream launches the Property Inspector.
Specify values for the properties and close the Property Inspector when complete.

Understanding role references Role references allow the bean developer to use logical role names within the bean's code. The application assembler or deployer can then map the reference to an actual role in the operational environment. The following entries are made in the <security-role-ref> node of the deployment descriptor.

JAR Designer property name	XML tag	Description
Name	<role-name>	The role name as it is used within the EJB.
Role-link	<role-link>	The actual role name specified in the application assembly portion of the deployment descriptor. It must exactly match.
Description	<description>	A textual description of role reference. This is useful for application assemblers, bean deployers, and administrators. Optional.

For an example of how role references are used, see the EJB section of the online Application Techniques.

To add a resource references:

Highlight the Environment icon, right-click and choose Add Resource Reference.

SilverStream creates an entry called UntitledResourceReference.
Highlight the UntitledResourceReference, right-click and choose Properties.

SilverStream launches the Property Inspector.
Specify values for the properties and close the Property Inspector when complete.

Resource references Resource references allow access to external resources like javax.sql.datasources, java.net.URLs, javax.jms.QueueConnectionFactories and so on. They allow the application assembler or deployer to customize the reference to a object in the operational environment. The values are added to the <resource-ref> node of the deployment descriptor and have the values shown below.

JAR Designer property name	XML tag	Description
Name	<res-ref-name>	The database or resource name. This is the name that will be registered with JNDI.
DataSource type	<res-type>	Resource type.
Authorization type	<res-auth>	Specifies who performs the login to the resource. Values can be container or application.
Description	<description>	A textual description of this resource.

For an example of how resource references are used, see the EJB section of the online Application Techniques.

To add persistent field definitions (entity beans only):

Highlight the Persistent Fields icon, right-click and choose Add.

SilverStream displays the Edit Persistent Fields dialog
Choose the fields from the dialog, and press OK when you are done.

SilverStream adds the field names to the deployment descriptor.
NOTE If the field is a complex data type, for example, an AddressData object that has instance variables of its own, you should only add the AddressData object as the persistent field. At deployment, you can map the constituent parts of the complex data type (like the city field) to appropriate database columns.

For more information, see Deployment Plan Designer.
To add a description of the field, highlight its name, right-click and choose Properties.

Adding Application Assembly information

The tasks described in this section relate to the components in the Application Assembly section of the deployment descriptor (the <assembly-descriptor> node in XML). Entries are not required for these components. If no values are specified SilverStream substitutes the default values described in each area.

To specify roles:

Highlight the Roles icon, right-click and choose Properties.
Specify values for the properties and close the Property Inspector when complete.

Understanding roles Roles provide a way to group security permissions for a type of user (such as managers) or a group of users that will use an application in the same way (such as bank tellers). The application assembler must specify roles if the application requires that you set method permissions or are using role references. At deployment time, the deployer can map the role to an actual entity in the operational environment. The following values are added to the <security-role> node of the deployment descriptor

JAR Designer property name	Tag name	Description
Name	<role-name>	The role name created by application assembler. There should be an entry for each role in the deployment environment. At deployment these roles are mapped to individuals or groups in target environment.
Description	<description>	A textual description of this role.

JAR Designer property name

Tag name

Description

Name

<role-name>

The role name created by application assembler.

There should be an entry for each role in the deployment environment. At deployment these roles are mapped to individuals or groups in target environment.

Description

A textual description of this role.

To specify method permissions:

Highlight the Method permissions icon, right-click and choose Add.

SilverStream creates an entry called Untitled Permission.
Highlight the UntitledPermission, right-click and choose Properties.
Specify values for the properties and close the Property Inspector when complete.

Usage tips When you choose Edit Roles, SilverStream launches a dialog from which you can choose the appropriate roles from the list of existing role.

When you choose Edit Methods, SilverStream launches a dialog that lists all of the beans and their methods that reside in the EJB JAR. You can choose one or more methods from one or more bean. Specify * to include all of the methods in a bean.

The first line of Description is used for the Name field.

Rules for specifying method permissions

These values are additive.
You can specify a wild card to allow all the specified users access to all methods.
If you do not specify method permissions the default is to allow all users in all roles to call methods.
If you specify method permissions for one method in the JAR, you must specify method permissions for all methods. If you specify method permissions for only a subset, SilverStream assumes that none of the other methods can be called by any user in any role.

Understanding method permissions Method permissions allow you to specify the methods that users in a specific role can execute.

The following values must be added to the <method-permission> node of the deployment descriptor.

JAR Designer property name	XML tag	Description
Name	<role-name>	The role name created by application assembler. Specify a name for this set of method permissions. This name is used within the deployment descriptor only. It provides a way to differentiate multiple method permission specifications. You might provide a name that you can use to logically group these values like Access to employee salary information.
Roles	<role-name>	The name of the role that has execute permission to the methods listed in this section.
Method	<method> <ejb-name> <method-name> <method-name>	Choose Edit Methods... SilverStream launches a dialog that lists all of the beans and their methods that reside in the EJB JAR. You can choose one or more methods from one or more bean. Specify * to include all of the methods in a bean.
Description	<description>	A textual description of the method permission.

Rules for specifying method permissions These rules are as follows:

The values are additive.
You can specify a wild card to allow all the specified users access to all methods.
If you do not specify method permissions the default is to allow all users in all roles to call methods.
If you specify method permissions for one method in the JAR, you must specify method permissions for all methods. If you specify method permissions for only a subset, SilverStream assumes that none of the other methods can be called by any user in any rule.

To specify transaction attributes:

Highlight the Transactions icon, right-click and Choose Add.

SilverStream creates an entry called UntitledTransaction.
Highlight UntitledTransaction, right-click and choose Properties.
Specify values for the properties and close the Property Inspector when complete.

Usage tips You can choose an Attribute from the drop-down list box. If you do not specify a transaction attribute, the SilverStream container defaults to Supports.

The first line of the description is used for the Name field.

Understanding transaction attributes Transaction attributes define a method's ability to participate in a transaction context. They are defined in the <container-transaction> node of the deployment descriptor and include the following entries.

JAR Designer property name	XML tag	Description
Name	<description>	A name that provides a way to group methods under a transaction attribute. The Name is only used by the deployment descriptor to differentiate multiple transaction attribute specifications. You might want to provide a name that you can use to logically group these values like Methods with no transactions.
Attribute	<trans-attribute>	The transaction attribute to apply to the methods in this group. If you do not specify a transaction attribute, the SilverStream container defaults to Supports.
Method	<method> <ejb-name> <method-name> (additional methods) <trans-attribute>	This node lists the set of methods that have a particular transaction attribute. You can choose one or more methods from one or more bean. Specify * to include all of the methods in a bean.
Description	<description>	A textual description of the transaction.

The EJB specification defines the following values for the <trans-attribute> entries.

Transaction attribute	Description
Mandatory	The method must be called within an existing transaction context.
Never	The method must be invoked without a transaction context. If a client tries to call the method within a transaction context, the Container throws the java.rmi.RemoteException.
NotSupported	The container will not start a transaction and will suspend one if it exists.
Required	Runs in an existing transaction, or starts a new transaction which is committed when the method returns.
RequiresNew	The Container always starts a new transaction and commits it when the method returns. Any existing transaction is suspended until the method returns.
Supports	The container will not start a transaction, but will run the method within an existing transaction context if one exists. If you do not specify a transaction attribute, the SilverStream container defaults to Supports.

Creating composite EJB JARs

During application assembly, you might want to combine EJBs from one or more EJB JARs into one application. Because SilverStream requires that any bean references resolve to beans in the same EJB JAR, you might need to create a new composite EJB JAR that includes the contents of two or more different EJB JARs.

To create a composite EJB JAR:

Make sure the EJB JARs are on the SilverStream server.
Click the EJB Jars and Media icon in the left pane.
Click on the New button in the right pane and click Create EJB Jar.

The JAR Designer appears.
From the JAR Contents tab, choose EJB Jars and Media.
Open the Jars tree control.
Select the EJB JAR to include in the JAR file, and double-click the EJB JAR or choose the > button to add it to the JAR file list. Repeat this step for each EJB JAR that you want to add to the combined EJB JAR.
After you have added all of the components to the JAR file, save and name it.

SilverStream recommends that you create composite JARs from the EJB JAR not from the remote JAR.

Once you have added the components to the composite JAR, you can map the references to any EJB in that JAR.

Validating the deployment descriptor

You can test to see if the deployment descriptor is correct and complete before deploying your EJB JAR. An EJB JAR with an invalid deployment descriptor can be saved but not activated on the SilverStream server.

The Validate EJB Jar option validates the deployment descriptor within the specified EJB JAR file. It reports any deployment descriptor problems, missing application assembly components, and class-related problems. The problems are written to a message dialog.

To validate the EJB JAR's deployment descriptor:

Click the EJB Jars and Media icon in the left pane.
Open the EJB JAR containing deployment descriptor you want to validate.
Choose File>Validate EJB JAR.
SilverStream displays a Validation Status dialog similar to the one shown here when it completes.

Deploying EJB JARs

To deploy an EJB JAR, you must first create an EJB Deployment Plan using the Deployment Plan Designer.

To access the Deployment Plan Designer:

Highlight the EJB JAR file that you want to deploy and either:
- Right-click and choose Create EJB JAR Deployment Plan
  
  or
- Choose File>Create EJB JAR Deployment Plan

SilverStream launches the Deployment Plan Designer.

For more information, see Deployment Plan Designer.

Modifying EJB JARs

You can modify an EJB class, home or remote interface at any point in the development or deployment cycle. To ensure that the latest classes are included in the EJB JAR, you simply rebuild the EJB JAR.

For more information about how this command works, see the Rebuilding JAR files.

Tools Guide