Importing interfaces from registered ActiveX components  Chapter 6: Enterprise JavaBeans Overview

Chapter 5: Defining Component Interfaces

Defining modules, interfaces, and types in IDL

EAServer stores all component interfaces in Interface Definition Language (IDL) modules. In EAServer Manager, the IDL folder displays all modules available in EAServer’s interface repository.


Learning IDL

IDL is defined by the Object Management Group as a standard language for defining component interfaces.

Chapter 3, “OMG IDL Syntax and Semantics,” in the CORBA V2.3 Specification defines IDL. Printable versions of this document can be downloaded from the following URL:

http://www.omg.org/corba/index.html

Creating and editing IDL modules, interfaces, and types

EAServer Manager displays IDL modules as folders beneath the top-level IDL folder. Modules can be nested, that is, a module may be defined within another module.

StepsNavigating nested IDL modules

Follow this procedure to view the IDL entities defined within a module.

  1. Expand the top-level IDL folder.

  2. Each icon in the IDL folder represents a top-level IDL module. To navigate to a nested module, click the + sign next to the parent module’s icon, or double-click the parent module’s icon.

  3. In the left pane, highlight the module of interest. EAServer Manager display the types and modules defined within the highlighted module in the right pane.

StepsDefining new IDL modules

  1. If defining a new top-level module, highlight the IDL folder.

    If defining a nested module, follow the steps in “Navigating nested IDL modules” to highlight the parent module.

  2. Choose File | New IDL Module. Enter the module name and click Create New Nested Module IDL. Module names must begin with a letter.

  3. EAServer Manager displays the empty module definition in the IDL Editor window. Optionally make the following changes:

    1. Edit the HTML documentation comment and add a description of the module.

    2. If the module will contain datatypes and interfaces (and not just nested modules), optionally specify the Java package for stubs as described by “Specifying Java package mappings for IDL modules”.

  4. When done, choose File | Save, then File | Exit to close the IDL Editor window.

StepsSpecifying Java package mappings for IDL modules

  1. If an IDL module contains datatypes and interfaces (and not just nested modules), you can specify the Java package to be used for generated Java stubs. Stubs for each type of Java client must be in different packages, or deployed under different code bases.

    If you do not specify a Java package mapping, stubs are generated to a package that matches the IDL module name. For example, stubs for module foo::bar are generated in Java package foo.bar.

    Change the Java package mapping for a module by editing one of the following files:

    To change the default Java package, create or edit an entry in the appropriate file with this format:

    idl-module=dotty-package
    

    Where:

    For compatibility with IDL created in previous releases, EAServer also allows you to specify the Java package in a doc comment directives above the module declaration. These directives are translated to entries in the java.props, ejb.props, or jdbc.props files. You can enter multiple directives to specify packages for stubs of different types. Each package directive has the form:

    /*
    ** <!-- typePackage: dotty-package -->
    */
    

    Where dotty-package is the dot-format Java package name and type is one of:

    You can also create or change Java package mappings when generating stubs for the IDL module in EAServer Manager. Highlight the IDL module and choose File | Generate Stubs. Choose the stub type and enter a different Java package name in the Java Package field.

StepsCreating IDL types, exceptions, and interfaces

Follow this procedure to define new datatypes and exceptions in a module. You can also define new component interfaces with this procedure, but it is easier to define interfaces using the component’s Interfaces folder (see “Defining interfaces graphically”).

  1. Navigate to and highlight the module where the entity is being created, as described in “Navigating nested IDL modules”.

  2. Choose File | New IDL Entity.

  3. In the New IDL Entity dialog box, enter a name for the type or interface, then choose the type of entity being created. Click Create New IDL Entity.

    EAServer Manager displays a template for the new IDL definition in the IDL Editor window.

  4. Finish the definition, then choose File | Save and File | Exit to close the IDL Editor window.

NoteEAServer allows forward IDL references You can create new IDL types that refer to other IDL types that do not yet exist; among other benefits, this feature allows you to create mutually recursive interface definitions. However, you must be sure that all references are resolved before you can generate stubs and skeletons. When generating stubs and skeletons, EAServer Manager will report errors for any unresolved type references.

StepsEditing IDL types, exceptions, and interfaces

To edit or delete a type, exception, or interface:

  1. Navigate to and highlight the module where the entity is being created, as described in “Navigating nested IDL modules”.

  2. The module’s types, exceptions, and interfaces display in the right pane of the EAServer Manager window.

  3. To edit an item, highlight it and choose File | Edit Entity IDL. Make your changes in the IDL editor window, save them, and close the window.

  4. To delete an item, highlight its icon and choose File | Delete.

NoteUnreferenced IDL definitions The interfaces, types and exceptions associated with a component are not deleted when you delete the component from EAServer Manager unless you delete the package or application where it is installed and specify full deletion. Unused definitions cause no harm. When generating Java stubs, stub classes are generated for all types in a module, regardless of whether the component references them. You can delete unreferenced IDL types to prevent the generation of unnecessary Java stub classes. Verify that no other component references an IDL definition before deleting it.

When deleting packages, you can delete everything associated with the package, including IDL definitions, by choosing full deletion as described in “Modifying packages”.


Using the IDL editor window

The IDL editor window is displayed when you create a new module or interface. You can also display the source code for datatypes, exceptions, and interfaces by right-clicking on their icons and choosing Edit IDL from the popup menu.

The File menu contains the following options:

Option

Description

Open

Allows you to replace the editor’s current contents with the contents of an operating system file.

Save

Saves your changes in the EAServer IDL repository. When you save to the repository, EAServer Manager checks the syntax of the module or declaration and displays any syntax errors.

Save As

Allows you to save the contents of the editor window into a specified file. This option can be used to export IDL definitions of EAServer interfaces for use with other vendor’s CORBA ORB implementations.

Exit

Closes the editor window without saving.

The current IDL editor does not have menu commands for copying, cutting, and pasting text. However, you can use the standard keyboard commands for your platform as described below:

Platform

What you do

Windows

Use the mouse to select text. Use Control+C to copy, Control+V to paste, and Control+X to cut.

UNIX (all)

Use the mouse to select text. Key mappings are defined by your X-Windows display configuration. Most workstation keyboards have Copy, Cut, and Paste keys that work as labeled with the manufacturer’s default X-display configuration. See your X-Windows system documentation for more information.


Creating and editing interfaces

Interfaces can be added in EAServer Manager, creating a blank interface declaration, or you can declare the interface yourself by editing the module’s IDL definition.

NoteChoosing an interface name Interface names are restricted as follows:

Sybase recommends that you begin interface names with a capital letter, and operation names with a lowercase letter.

NoteSupported preprocessor directives No IDL preprocessor directives other than #include are supported.

StepsCreating new interfaces in EAServer Manager

  1. Highlight the module’s icon and choose File | New IDL Entity.

  2. Type the name of the new interface, choose Interface in the dropdown list of IDL entity types, and click Ok.

  3. Click Ok.

  4. EAServer Manager displays a new, blank interface in the IDL Editor window. Edit the declaration if needed.

  5. When done, choose File | Save, then File | Exit to close the IDL Editor window.

StepsEditing an existing interface

  1. Select the interface’s icon and choose File | Edit IDL.

  2. EAServer Manager extracts the interface definition from the module and displays it in the IDL editor window.

  3. Edit the declaration as needed.

  4. When done, choose File | Save, then File | Exit to close the IDL Editor window.

IDL interface declarations

Interfaces are declared as shown below:

interface InterfaceName [: BaseInterface1, BaseInterface2, ...] {
  operations
};

where:

For example, this interface, StockComponent, inherits from no other interface:

interface StockComponent {
};

This interface, C, inherits from interfaces A and B:

interface C : A, B {
}

Interfaces that inherit definitions from other interfaces are subject to the following constraints:

The sections below describe how to define operations and attributes for the interface.

Interface stub generation directives

You can embed specially formatted comments in IDL to control the generation of Java stubs for IDL interfaces and structures. Directives must appear in a block comment located immediately before the IDL interface or struct declaration.

Imported class name This directive specifies that a structure or interface was imported from a Java class, and that a new version of the imported class must not be generated when stubs are generated. This directive is most commonly used for EJB home and remote interfaces and EJB primary keys that were defined by importing EJB classes or EJB-JAR files.

The format is:

** <!-- imported classname -->

Where classname is the Java class name, in dot notation. For example, foo.bar.MyBeanHome or foo.bar.MyBeanPrimaryKey.

Is home interface This directive identifies an interface as a home interface used by EJB clients and components. If you specify a home interface for a component as described in “Changing the EJB remote or home interface”, EAServer Manager adds this directive. The format is:

** <!-- home -->

Finder method return type Applies to multi-object finder methods in an EJB entity bean’s home interface. If a finder method’s Java form must return java.util.Enumeration, add a doc comment of this form above the IDL finder method declaration:

/*
** <!-- java.util.Enumeration -->
*/
::MyModule::MyRemoteList findByName(in string name);

See “Defining home interface methods” for more information on EJB finder methods.

Operation declarations

Operations in an IDL interface become component methods when the interface is assigned to a component. You can define operations directly in IDL, or graphically as described in “Defining interfaces graphically”. If you define operations in IDL, follow the structure described here.

Operations are declared as follows:

returnType opName 
( 
[ ... parameterList ... ] 
)
[  raises ( ... exceptionList ... ) ] ;

where:

Attribute declarations

Attributes allow you to associate a value with an interface. IDL attributes are similar in concept to structure fields in languages such as C. However, when mapped to a programming language, attribute values can typically be accessed only by generated functions that allow you to set and retrieve the attribute’s value.

NoteAttributes are not supported by ActiveX components and clients.

Attributes are declared as shown below:

[ readonly ] attribute TypeSpec name;

where

In C++ and Java, a read-only attribute maps to a method with the same name that returns the attribute type. A writable attribute maps to a pair of overloaded methods with the same name as the attribute. For example, consider the following IDL declarations:

readonly attribute long days; // readonly
attribute long months;        // writable

In a C++ or Java implementation of the interface, these methods must be declared:

long days();
long months();
void months(long new_months);

NoteCurrently, attributes do not do not display with a component’s methods in EAServer Manager. Use the IDL editor to view attribute definitions.

Datatypes for parameters and return values

To define parameter and return value datatypes, you can use EAServer’s predefined IDL datatypes or your own user-defined IDL types. In addition, EAServer extends IDL to allow the use of Java class names. The sections below describe each option in detail.

Predefined IDL datatypes EAServer ships with predefined datatypes for use in declaring parameter and return value datatypes. Predefined datatypes include all CORBA base types (except for the CORBA::Any type) and equivalents for database result sets and other commonly used database column types such as date, time, and timestamp.

EAServer Manager’s Method Properties dialog box displays the predefined datatypes in the drop-down lists for Parameter and Return types. “Predefined datatypes” lists EAServer’s predefined IDL datatypes, the equivalent display names, and a description of each.

For descriptions of the datatypes defined in the BCD, MJD, or TabularResults modules, see the documentation in the html/ir subdirectory of your EAServer installation. (Or, load the main EAServer HTML page in your Web browser, and click the Interface Repository link). If you use types from these modules, add an include directive for the appropriate module at the top of the module that defines your interface. For example:

#include <TabularResults.idl>

Internally, TabularResults.idl includes both BCD.idl and MJD.idl. You need not include BCD.idl and MJD.idl explicitly if you have already included TabularResults.idl.

User-defined IDL datatypes In addition to EAServer’s predefined datatypes, you can define your own datatypes in IDL and use them to declare return types and parameters.

All IDL type definitions are allowed, with these exceptions:

User-defined types must exist in the EAServer IDL repository before you can use them in interface declarations. For information on defining datatypes, see Chapter 3, “OMG IDL Syntax and Semantics,” in the CORBA 2.3 specification.

In some cases, you must use the full scope name. In a parameter list, use a type’s full scope name if any of the following is true:

For example, consider the IDL:

module MyMod {
    typedef string MyType;
    interface MyIntf {
        typedef double MyOtherType;
        ....
    };
};

With these declarations, MyMod::MyType is the full scope name for MyType and MyMod::MyIntf::MyOtherType is the full scope name for MyOtherType.

Java class names used as IDL datatypes EAServer’s IDL compiler extends IDL to allow Java class names as parameter and return types for methods. This feature provides functionality that is similar to the proposed Objects by Value CORBA extension (OMG TC Document orbos/98-01-18, Objects By Value). Specifically, you can pass a copy of an object rather than passing an interface pointer that refers back to the original object.

You can specify any Java class name for a method input parameter or return type as long as:

Note the following restrictions for methods that are defined using Java datatypes rather than IDL or predefined EAServer Manager types:

User-defined exceptions

Exceptions can be declared in a module or interface. Exceptions are declared as follows:

exception name {
    ... memberList ...
};

where name is the name of the exception and memberList is an optional list of member field declarations. This list has the form:

exception MyException {
    type1 member1;
    type2 member2;
    ...
};

Where type1, type2, and so forth are IDL type names (other than CORBA::Any) and member1, member2, and so forth are the names of the member fields.

Once you have defined an exception, you can use it in the raises clause when defining operations for an interface, as described in “Operation declarations”.

NoteUser-defined exceptions are not supported by ActiveX components and clients.


Adding IDL documentation comments

EAServer Manager creates HTML documentation files for each IDL module in the html/ir subdirectory.

At a minimum, the HTML file lists the datatypes and interfaces defined in the module. You can embed additional documentation text for a datatype, interface, or method in a C-style comment placed immediately above the declaration. EAServer ignores C++-style line-end comments when generating HTML documentation. That is, text within comments that use double slashes, //, to delineate the comment text is ignored.

Within the C-style comment, add text describing the item to the comment, as in the example below. If desired, you can use HTML codes to format the text. But do not use heading tags such as <H1>, <H2>, and so forth, because they conflict with tags that are already used to structure the sections of the generated output.

The IDL fragment below contains an example of a documentation comment:

/**
 ** Example method to demonstrate user-defined
 ** exceptions.
 ** <P>Pass <I>yes_no</I> as <code>true</code> 
 ** if you want an exception thrown.
 ** <P>Returns input value of <I>yes_no</I>
 ** parameter.
 */
boolean throwException 
(
in boolean yes_no
)
raises 
(
myException
);

You need not use the spacing conventions illustrated in this example. EAServer Manager treats any C-style comment as an IDL documentation comment. However, when you save in the IDL Editor window, EAServer Manager reformats all C-style comments to match this example’s spacing convention.

NoteStub generation directives in IDL comments You can embed directives in IDL comments to affect the Java stubs generated for a module or interface. See “Interface stub generation directives” for more information.


Refreshing the HTML documentation

HTML documentation is not generated automatically. You must use EAServer Manager to create or update documentation for new or changed IDL modules. In EAServer Manager, highlight a component, package, server, or module, then select File | Generate HTML. The top level index.html file is updated only when you generate HTML for a server.

To update documentation for all IDL modules in the EAServer interface repository, generate HTML for any server. To selectively update documentation for interfaces used by components, generate HTML for a component or package; EAServer Manager will generate documentation for all IDL modules used in the component or components within the package. To update only the documentation for a single module, highlight that module then select File | Generate HTML.


Viewing HTML documentation for IDL modules

EAServer creates HTML documentation for all imported IDL modules in the style of Sun’s javadoc tool. At a minimum, this documentation lists the datatypes and interfaces defined in the module, including structure fields, array lengths, parameter names and datatypes, exceptions thrown by methods, and so forth. When editing IDL, you can also create specially-formatted comments that provide descriptions of entities declared in the IDL file, as described in “Adding IDL documentation comments”.

Module documentation can be viewed in a Web browser by connecting to your server with this URL:

http://yourhost:yourport/ir/

where yourhost is the host name and yourport is the HTTP port number.


Importing existing IDL modules

You can import interfaces defined in CORBA IDL into the EAServer interface repository. There are two ways to import a module:

To deploy IDL types and interfaces that are not declared within a module, place the IDL file that defines them in the EAServer Repository subdirectory and restart EAServer if it is running.

You can repeat the procedures above to redefine existing IDL definitions.





Copyright © 2005. Sybase Inc. All rights reserved. Chapter 6: Enterprise JavaBeans Overview