Tools Guide

Chapter 7 Business Object Designer

The Business Object Designer gives you an object-oriented, visual environment for creating SilverStream business objects. You can create packages to contain your business objects, Java interfaces, Common Object Request Broker Architecture (CORBA) Interface Definition Language (IDL), and Enterprise JavaBeans.

You use the Programming Editor, in the lower portion of the Designer, to write Java Code for the objects you create. For information about using the Programming Editor, see Programming Editor.

This chapter describes the following:

Creating packages

The SilverStream Business Object Designer lets you create your own Java packages for business objects. Packages let you organize, group, and separate your business objects. It also lets you control the use of the Java class name space. Packages appear in the SilverStream Designer as directory trees.

To create a Java package:

Select the Object and New icons in the SilverStream Designer. A popup menu appears.
Select New Package from the menu. The Create a New Package dialog appears.
Enter a name for your package and press OK.

Your new package appears in the right pane of the SilverStream Designer. If you already had a package selected, the new one appears below the current selection. If you had a business object selected, the new package appears on the same level in the directory. If you do not have anything currently selected, the new package appears at the top level of the hierarchy. If you have an item selected and want to create a top-level package, unselect the item by pressing Ctrl and clicking the selected item.

Creating interfaces

To create a Java interface:

Select the Object and New icons from the SilverStream Designer. A popup menu appears.
Select New Interface from the menu. The Interface Wizard dialog appears.
Press Add Interface to add the name of an existing interface that will be extended by the interface you are creating.
Press OK. The interface name you entered appear in the Interface Wizard dialog. Repeat Steps 3 and 4 if your new interface extends more than one other interface.
Press Next when you finish specifying Java interfaces. The next Interface Wizard screen appears.
Enter a name for your new Java interface and press Finish. The Business Object Designer appears. Write the methods that the new interface defines in the edit area of the Business Object Designer.

Creating CORBA IDLs

CORBA specifies a framework for distributed objects. You can use CORBA as a model for defining and using multilanguage objects, as a protocol for inter-machine communication, and as a set of runtime services. The CORBA IDL allows the client program (for example, a Java applet or application) to make direct calls to the object. For more information, see the CORBA chapter in the Programmer's Guide.

NOTE You must create a CORBA IDL within a package. Do not place two top-level CORBA objects within the same package.

To create a CORBA IDL:

Select CORBA IDL from the Business Object popup menu. The CORBA IDL Wizard appears.
Enter the name of the JAR file that will contain the Java classes generated by the interface.
Check the Top level object check box if the CORBA IDL you are defining is going to be the main interface definition. If you are going to include this file within another file, leave this check box blank. Press Next.
Enter a name for the CORBA IDL and press Finish. The Business Object Designer appears. You can enter and edit your interface definitions in the Business Object Designer's edit area.

Creating Enterprise JavaBeans

Enterprise JavaBeans (EJBs) are Java-based components that are remotely accessible, transactional, and secure. EJBs require:

A remote interface
A home interface
A session or entity bean class
A primary key class (for some types of entity beans)

SilverStream provides a wizard that builds the shell, and when possible, the method bodies of each of these components.

Choosing the right wizard option You can use the EJB Create Wizard in one of these ways:

Option	Description
Create a new Session Bean	Creates the session bean implementation class and the home and remote interfaces. The resulting EJB components will contain only the methods that you specify in the wizard.
Create a Session Bean from an existing component	Creates a session bean implementation class from an existing remote interface, or a remote interace from an existing session bean implementation class. It always generates the corresponding home interface. You might use this option when: You like to define your remote interface (or bean class) first and want to generate the other EJB components based on the one you completed. You used the Create a new Session Bean option and subsequently changed either the implementation class or remote interface and want to update the remaining components. NOTE When you use this option, it generates a new home interface and a new implementation or remote interface (depending on what you've specified). This means that any changes that you've made to the generated components will be overwritten. You cannot use this option to copy components from other databases.
Create a new Entity Bean	Creates the entity bean implementation class, the home and remote interfaces and possibly a primary key class. The resulting EJB components will contain the fields that you specify along with corresponding accessor methods for each field that you specify in the wizard.
Create an Entity Bean from an existing component	Creates an entity bean implementation class from an existing remote interface; or creates a remote interace from an existing entity bean implementation class. It always generates the corresponding home interface, and the primary key class (if needed). You might use this option when: You like to define your remote interface (or bean class) first and want to generate the other EJB components based on the one you completed. You used the Create a new Entity Bean option and subsequently changed either the implementation class or remote interface and want to update the remaining components. NOTE When you use this option, it generates a new home interface and a new implementation or remote interface (depending on what you've specified). This means that any changes that you've made to the generated components will be overwritten.
Create a new Entity Bean based on a table	Creates the entity bean implementation class, the home and remote interfaces and the primary key class (if needed) based on the database table and fields that you select. The resulting EJB components will contain the database fields that you selected along with the corresponding accessor methods for each of the selected database fields.

Choosing Cancel Choosing cancel exits the wizard and does not create any EJB components. If you want to generate EJB components that just contain stubs for the EJB interface methods, you must complete the wizard. For session beans you must add at least one method and for entity beans you must add at least one field. Since you will be editing the resulting components, you can simply remove or modify the method or field as required.

How the wizard names the EJB components it creates The EJB Create Wizard uses the following rules for naming EJB components:

For bean classes, prepends SB (for session beans) or EB (for entity beans) and appends Bean to the root name.
For remote interfaces, prepends SB and appends nothing to the root name.
For home interfaces, prepends SB and appends Home to the root name.

If you've selected a package before starting the EJB Create Wizard, the wizard creates the components in this package by default. If the packages or subpackages do not exist, the EJB Create Wizard creates them for you. You always have the option to specify a different package.

How the wizard names member variables The EJB Create Wizard uses the following rules for naming variables:

Prefaces variables with m_
For entity beans created from a database table, the wizard prefaces the database field name with m_.

How the wizard generates ejbCreate() and ejbPostCreate() methods The wizard creates a single ejbCreate() and a matching ejbPostCreate() for both session beans and entity beans. The ejbCreate() contains no parameters. You can modify the existing methods and add new ones as needed in the Programming Editor.

How the wizard handles the EJBContext For both session and entity beans, the wizard generates protected member variables like these:

  protected SessionContext m_context;
  protected EntityContext m_context;

It then saves the session or entity context to these member variables in the appropriate methods. For example, it saves the SessionContext like this:

  public void setSessionContext(javax.ejb.SessionContext
    sessionContext1) throws java.rmi.RemoteException
  {
      m_context = sessionContext1;
  }

For entity beans it also resets the the context in the unsetEntityContext() method like this:

  public void unsetEntityContext() throws java.rmi.RemoteException
  {
     m_context = null;
  }

How the wizard handles imports The EJB Create wizard determines which Java import statements are necessary based on the code that it generates and imports only the necessary packages or classes.

Entity beans and primary key classes The wizard creates a primary key class when:

You specify more than one field for the primary key (even if both fields are Java classes like String or Integer).

The wizard will not create a primary key class when:

You specify a single field from a table and that field is a Java class like String or Integer.
You specify a single field from a table and that field is a primitive (like int), the wizard changes it to the corresponding object type and does not generate a primary key class.

Entity beans and data types The following table describes how database data types are translated to the appropriate Java data type.

Database data type	Java data type
CHAR, VARCHAR, LONGVARCHAR	String
NUMERIC, DECIMAL	java.math.BigDecimal
BIT	boolean
TINYINT	byte
SMALLINT	short
INTEGER	int
BIGINT	long
REAL, FLOAT	float
DOUBLE, BINARY, VARBINARY	double
LONGVARBINARY	byte[]
DATE	java.sql.Date
TIME	java.sql.Time
TIMESTAMP	java.sql.Timestamp
UUID	java.rmi.server.UID
BLOB	java.sql.Blob
CLOB	java.sql.Clob

Creating session beans

To create a session bean (not based on other components):

Select the Object icon and the New icon from the SilverStream Designer. A popup menu appears.
Select New Enterprise JavaBean. The first Create EJB Wizard screen appears.
Select Create a new session bean, then choose Next.
Enter the root name for the session bean and its components, specify a package name and choose Next.
Enter the number of methods that this session bean should contain and choose Next.

Do not include any of the javax.ejb.SessionBean interface methods or an ejbCreate() method. These are added automatically by the wizard.

You can add and remove methods later if you do not yet know exactly which methods you need.
Select the check box for the class or interface that you want to edit once the wizard completes or unselect all of the check boxes if you do not want to edit any of the classes at this time.
Choose Finish.

The EJB Create Wizard creates the session bean's home and remote interfaces and the bean class in the specified package and launches the selected component in the Programming Editor.

To create a session bean from an existing component

Select the Object icon and the New icon from the SilverStream Designer. A popup menu appears.
Select New Enterprise JavaBean. The first Create EJB Wizard screen appears.
Select Create a session bean from an existing component, then choose Next.
Enter the name of the remote interface or implementation whose contents you want propagated to the other EJB components.

For example, you would specify the remote interface name here, if you have added business methods to it and you want those business methods added to the implementation class.

The wizard notifies you if there are existing EJB components that will be overwritten if you continue.

If you do not allow the overwrite, you must exit the wizard and rename the EJB components that will be overwritten or you cannot continue.

If you do allow the overwrite, the wizard regenerates the home interface and the other component (remote interface or implementation class) that needs to be updated.
When prompted, select the checkbox for the class or interface that you want to edit once the wizard completes, then choose Finish.

Creating entity beans

To create an entity bean

Select the Object icon and the New icon from the SilverStream Designer. A popup menu appears.
Select New Enterprise JavaBean. The first Create EJB Wizard screen appears.
Select Create a new entity bean, then choose Next.
Enter the root name for the entity bean and its components, specify a package name and choose Next.
Enter the number of fields that this entity bean should contain and choose Next.
For each field that you select, the wizard prompts you for the following information:
- The field name and data type.
- Whether this is field is part of the primary key.
- Whether this field is persistent.
- Whether to create a get method for this field, and if it creates the get method whether it should add the method to the bean class only, or to the bean class and the remote interface.
- Whether to create a set method for this field, and if it creates the set method whether it should add the method to the bean class only, or to the bean class and the remote interface.
Select the checkbox for the class or interface that you want to edit once the wizard completes, then choose Finish.

The EJB Create Wizard creates the entity bean's home and remote interfaces and the bean class in the specified package and launches the selected component in the Programming Editor.

To create an entity bean from an existing component

Select the Object icon and the New icon from the SilverStream Designer. A popup menu appears.
Select New Enterprise JavaBean. The first Create EJB Wizard screen appears.
Select Create an entity bean from an existing component, then choose Next.
Enter the name of the remote interface or implementation whose contents you want propagated to the other EJB components.

For example, you would specify the remote interface name here, if you have added accessor methods or persistent fields and you want them added to the implementation class.

The wizard notifies you if there are existing EJB components that will be overwritten if you continue.

If you do not allow the overwrite, you must exit the wizard and rename the EJB components that will be overwritten or you cannot continue.

If you do allow the overwrite, the wizard regenerates the home interface and the other component (remote interface or implementation class) that needs to be updated, as well as the primary key class if one is required.
When prompted, select the checkbox for the class or interface that you want to edit once the wizard completes, then choose Finish.

To create an entity bean based on a table

Select the Object icon and the New icon from the SilverStream Designer. A popup menu appears.
Select New Enterprise JavaBean. The first Create EJB Wizard screen appears.
Select Create a new entity bean based on a table, then choose Next.
Choose the database table from the list provided, then choose Next.
Enter the root name for the entity bean and its components, specify a package name and choose Next.
Select the fields that you want the entity bean to represent, then press Next.
For each field that you select, the wizard prompts for the following information:
- Whether this is field is part of the primary key.
- Whether this field is persistent.
- Whether to create a get method for this field, and if it creates the get method whether it should add the method to the bean class only, or to the bean class and the remote interface.
- Whether to create a set method for this field, and if it creates the set method whether it should add the method to the bean class only, or to the bean class and the remote interface.
When prompted, select the check box for the class or interface that you want to edit once the wizard completes, then choose Finish.

The EJB Create Wizard creates the entity bean's home and remote interfaces, the bean class and if necessary the bean's primary key class in the specified package and launches the selected component in the Programming Editor.

Creating utility classes

Utility classes are general-purpose Java Classes that you create as a triggerless object. You can use utility classes with any code running on the server, such as business objects and pages, as long as they are in the same database. To use utility classes with client-side Java applications (forms), or to use them with objects in another database, you must make them accessible from JAR files.

Create a utility class:

From the SilverStream Designer, select Objects in one of the databases.
Click the New icon (at the lower part of the Window) and select New Object.
Click Next on the initial dialog. (Do not select a trigger).
Follow each step in the wizard to create the class you want. That is, you specify which class it extends, which interface(s) it implements, and so on.
Once you have created the class, write the methods for the class.

You must write any import statements that you need.

Creating data source objects

A SilverStream data source object (DSO) is a triggered business object that extends the SilverStream data access model. You can use a DSO to retrieve data from any target data source. You can then pass the result set to SilverStream Java and HTML forms.

To create a DSO:

Select the Object icon and the New icon from the SilverStream Designer. A popup menu appears.
Select New Object. The first Business Object Wizard screen appears.
Select the Data Source check box and press Next. The second Business Object Wizard screen appears. This screen changes, depending on the type of business object you specified in the first screen. For Data source objects, the second Business Wizard screen prompts you to define the database table columns that your DSO will use. If you specify column definitions, it means that you can bind a control to one of those columns at design time.
Select Add. The Add Column Description dialog appears. Enter the column name and its type.
Press OK. Repeat this procedure until all of the table columns you want are specified.
Check the Updatable check box if you want your data source object to update the target database.
Press Next. The next Business Object Wizard screen appears.
Enter a name for your data source object in the Object name field.
Select the modifier appropriate for your business object in the Modifier field.
NOTE Triggered business objects like data source objects must have the Public modifier selected. This is the default.
Click on the down arrow in the Lifetime field to specify the object's lifetime. This is also known as persistence.
When you are through specifying information for your business object, press Next. You can also just press Next without making any changes if you want to accept the defaults for the object. The Business Object Designer appears.
Enter the code for your data source object in the Business Object Designer's edit area.

Creating servlets

You can use the SilverStream Business Object Wizard to create a Java servlet. Servlets are triggered when the SilverStream server receives an HTTP request.

To create a servlet:

Select Servlet (HTTP request) from the first Business Object Wizard screen and press Next. The next Business Object Wizard screen appears.
Press Add to specify the URLs that you want the servlet to respond to. The Add URL dialog appears.
When you finish specifying URLS, press OK. Each URL must be relative to the database where the business object is located. One servlet can respond to multiple URLs. The second Business Object Wizard screen appears.
Enter a name for the servlet and specify its modifier options and lifetime, or just press Next to accept the defaults.
NOTE Servlet names must follow the standard Java object naming conventions. You cannot use any SilverStream reserved words.

The next Business Object Wizard screen appears.
Specify any interfaces that you want your servlet to implement. If your servlet does not require any interfaces, press Finish. The Business Object Designer appears.
SilverStream implements the appropriate listener interfaces for the triggers that you define for your business object by default. SilverStream automatically implements the AgiHttpListener servlet interface.

The default servlet object event appears in the edit area of the Object Designer. This is the service() event on the AgoServletInvoker object. This event is defined in the javax.servlet.Servlet interface.

Creating table-triggered business objects

Another common type of business object is the table-modified business object. It listens for any modifications that are made to the database table you specify.

To create a table-modified business object:

Select Table modified from the first Business Object Wizard screen and press Next. The next Business Wizard screen that appears prompts you to select a database table to associate with the business object.
Select a table from the list of tables residing on the current database and press Next. The next Business Object Wizard screen that appears prompts you to enter a name for the business object.
Enter a name for the business object and specify any other options you want it to use or press Next to accept all the defaults. The next Business Object Wizard appears.
Specify any interfaces that the business object might use. Press Finish. The Object Designer appears. You enter code for the business object in the edit pane.

Adding objects to a package

To add new objects to a package:

Select a package and the New icon from the right pane of the SilverStream Designer. A popup menu appears.
Select either Object, Interface, or CORBA IDL, depending on the type of object you want to add. Follow the procedures outlined in the previous sections to create the specific object that you want to add to a package.

NOTE You can add existing objects to a package by opening the object in the Object Designer and selecting Save As from the File menu. If the package already exists, uncheck the Create Package if it doesn't exist check box.

Adding subpackages to a package

To add a subpackage to a package:

Select the package that you want to contain the sub-package. Select the New icon. The Object popup menu appears.
Select New Package. The Create New Package dialog appears. Enter a name for your new package and press OK. The new package appears as a subpackage in the SilverStream directory.

Tools Guide