Chapter 5 Defining Component Interfaces

Defining interfaces graphically

A component's Interfaces folder contains icons for the IDL interfaces implemented by the component. These interfaces define the methods that can be called by client applications.

When you define a new component, Jaguar Manager creates an interface for the component. If you defined the component by importing a Java or ActiveX class, the interface contains IDL definitions matching the Java or ActiveX methods. If you are defining a component from scratch, Jaguar Manager creates a new IDL interface with no methods. If you have imported an EJB component, the importer has also created an IDL home interface for the component.

Adding interfaces

Use these steps to configure which interfaces a non-EJB component implements, or to add interfaces to an EJB component in addition to the home and remote interfaces:

Highlight the Interfaces folder beneath the component icon and choose File | Add Interfaces. The Install Interfaces dialog displays.
You can perform the following operations in the dialog:
- Add an existing interface Choose from available interfaces as follows:
  1. Select the module that defines the interface in the dropdown menu.
  2. Highlight the interface name from the list of interfaces on the right side of the dialog box.
  3. Click Add.
- Add and define a new interface Use these steps if the interface you want to implement in the component does not exist. You can add methods to the interface after exiting the dialog:
  1. Enter a name for the new interface, in the format module::interface.
  2. Click Add New.
When you are done, click Install to close the dialog.
If you defined new interfaces, add methods to the interfaces as described below.

Removing interfaces

These steps remove an interface from the list of interfaces supported by a component, but do not affect the IDL definition:

Expand the Interfaces folder beneath the component icon. The list of interfaces supported by the component displays.
Highlight the interface to remove, and choose File | Remove.

Rules for removing interfaces:

An EJB component must have a home and remote interface; you cannot remove them. You can change them as described in "Changing the EJB remote or home interface".
A non-EJB component must support at least one interface to serve as its remote interface. You cannot remove the last interface supported by a component; instead, change the remote interface as described in "Changing the EJB remote or home interface".

Changing the EJB remote or home interface

Home and remote interfaces are used by EJB clients and components. To change a component's home or remote interface:

Expand the Interfaces folder below the component icon.
Highlight the Interfaces folder and choose File | Set Home interface if changing the home interface, or choose File | Set Remote Interface if changing the remote interface.
Enter an IDL name for the interface, specifying an IDL module hierarchy and interface name to match the intended Java package hierarchy and interface name. For example, if the Java class will be foo.bar.MyBeanHome, enter foo::bar::MyBeanHome. Jaguar Manager creates specified modules and interfaces if they do not already exist.

Editing interfaces

You can edit method signatures graphically in the Method Properties dialog, or by editing CORBA IDL directly. Some method properties such as the transactional attribute and run-as mode properties are not defined in IDL. To configure these settings, you must display the Method Properties window.

Interface and method name conventions Sybase recommends that you begin interface names with a capital letter, and method names with a lowercase letter.

Editing methods in IDL

You define or edit method signatures by editing the CORBA IDL interface definition directly. Use this procedure if you are comfortable with CORBA IDL and prefer it to point-and-click interface editing.

Highlight the icon for the interface of interest.
Choose File | Edit IDL
The IDL interface definition displays in the IDL Editor window.
Make any changes, then choose File | Save. If the changes have introduced syntax errors, Jaguar Manager displays the error text in a dialog box. Fix the errors, then try to save again.
When you have made all changes and saved them, choose File | Exit.

Adding methods graphically

Highlight the icon for the interface of interest.
Choose File | New Method.
Enter a name for the method and click Create New Method.
The Method Properties dialog box displays. Use the controls on the General tab to define the method parameters, return type, and exceptions raised. See "Method properties" for more information.

Editing method properties

Use this procedure to display the method properties window, which provides a point-and-click controls to edit the method's IDL signature and also configures settings that are not represented in IDL.

Highlight the icon for the interface of interest.
Highlight the icon for the method to be edited.
Choose File | Method Properties.
The Method Properties dialog box displays. See "Method properties" for more information.

Removing methods graphically

Expand the icon for the interface of interest.
Highlight the icon for the method to be deleted.
Choose File | Delete Method.

Method properties

Method properties are organized on the following tabs:

General Shows the method's return type, parameters, and the exceptions that can be thrown. The fields are described in the table below:

Table 5-1: General method properties
Property	Description	Notes
Description	Specifies a description of what the method does. The description can be up to 255 characters.	You can enter comments about the method here.
Exceptions Raised	Specifies the user-level exceptions raised by this method. Enter exceptions in the form: Module::ExceptionName You can enter multiple exceptions, separated by commas.	User-level exceptions must be defined in IDL before you can specify that a method raises the exception. See "User-defined exceptions" for more information.
Read only	Applies to entity components that use component-managed persistence (also called bean-managed persistence). Specifies whether the method can change the instance state.	For best performance, set this property for all entity component business methods that do not modify the instance state. When this property is enabled, the entity components ejbStore or ctsStore method is not invoked after the business method returns.
Returns	Specifies the return type of the method. Select the return type from the drop-down list or enter the name of an IDL or Java datatype into the input field. See "Parameter and return value datatypes" for more information.	Method implementations cannot return null values. If there are cases where the method must return no value, specify an IDL sequence type as the return value, and implement the method to return an empty sequence to indicate the no-value case.
Parameters	Displays the name, type, and mode of each parameter.	To add a parameter, click Add, and complete the information described in "Parameter properties". To modify a parameter, highlight the parameter you want to modify, click Modify, and complete the information described in "Parameter properties". To delete a parameter, highlight the parameter you want to delete, and click Delete.

Transactions Allows you to configure transaction properties for the method. The Transaction Attribute and Transaction Isolation Level settings have the same meaning as the like-named settings for components. See "Component properties: Transactions".
Permissions Applies to EJB 2.0 and 1.1 components only. The settings allow you to restrict which users can invoke the method. See "Configuring role references and method permissions" for more information.
Run-As Mode Applies to EJB 1.0 components only. Allows you to configure the user name and password for to be used for intercomponent calls. These settings have the same meanings as the Run-As Mode component settings. See "Component properties: Run-As Mode".
All Properties Allows you to manually edit method property settings in the EAServer configuration repository. For advanced users.

Parameter properties

The Parameter Properties dialog box appears when you click Add or Modify in the Method Properties window. The following table describes the controls within the window.

Table 5-2: Parameter properties
Property	Description	Notes
Parameter Number	Displays the parameter number	No input is required.
Name	Specifies the name of the parameter	A name is required.
Mode	Specifies how values are passed for the parameter.	Supported modes are as follows: in - Input only. No new value is returned when the method completes. inout - Input and output. Input values are not ignored, and output values are returned to caller. out - Output only. Input values will be ignored; output values are returned to caller.
Type	Specifies the datatype of the parameter.	Select a datatype from the drop-down list or type the name of an IDL or Java datatype in the input field. See "Parameter and return value datatypes" for more information.
Description	Describes how the parameter is to be used.	Optional. You can use this field to describe how the parameter is to be used.

Parameter and return value datatypes

For method parameters and return values, you can choose predefined types from the drop-down list or enter a Java or IDL datatype name by typing it in the input field.

Predefined datatypes

The following table lists the predefined Jaguar Manager datatypes and their IDL equivalents. These types display when you change the datatype of a parameter or change the method's return type.

Table 5-3: Predefined EAServer IDL datatypes
Jaguar Manager display datatype	CORBA IDL type	Description
boolean	boolean	One bit of binary data; a value that is either true or false
integer<16>	short	A 16-bit integer
integer<32>	long	A 32-bit integer
integer<64>	long long	A 64-bit integer
float	float	Single-precision IEEE floating point numbers
double	double	Double-precision IEEE floating point numbers
string	string	A sequence of characters of any length
binary	BCD::Binary	Sequence of bytes
decimal	BCD::Decimal	Fixed-point decimal
money	BCD::Money	Same as decimal
date	MJD::Date	A date including year, month, day, hour, minute, second, and millisecond values
time	MJD::Time	Holds the time of day, including hours, minutes, seconds, milliseconds
timestamp	MJD::Timestamp	Holds the same data as date, plus a nanoseconds value
ResultSet	TabularResults::ResultSet	A single table of relational database rows
ResultSets	TabularResults::ResultSets	A sequence of 0 or more ResultSet objects

Using IDL and Java datatypes

In addition to the predefined types listed in "Predefined datatypes", you can also apply IDL and Java datatypes to parameters and return values by typing the name of an IDL or Java datatype.

IDL datatypes You can define your own datatypes and use them when defining method signatures. "Defining modules, interfaces, and types in IDL" discusses IDL in more detail.

To specify an IDL type name in the Method Properties dialog box, simply enter the type name in the Returns or Parameter Datatype field--for example, MyModule::MyType . The IDL module must be present in the EAServer IDL repository, and the module must contain a declaration for that type name.

Java datatypes You can specify Java datatypes as input parameters or return types. You cannot specify Java datatypes for parameters that use the inout or output modes. "Java class names used as IDL datatypes" describes which interfaces and classes can be used.

To specify a Java datatype, simply type the full class or interface name in the Returns or Parameter Datatype field--for example, java.util.Properties .

Java datatypes and interoperability If a method is defined using a Java datatype, only Java components can implement the method and only Java clients can invoke the method.