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.

Navigating 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.

Defining 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.

Specifying 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:

   • Repository/IDL/ejb.props specifies the Java packages for EJB stubs.

   • Repository/IDL/java.props specifies the Java packages for Java/CORBA stubs.

   • Repository/IDL/jdbc.props specifies the Java packages for EAServer 1.1 stubs.

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

   idl-module=dotty-package
   

   Where:

   • idl-module is the IDL module name, for example, com::sybase::test::MyModule

   • dotty-package is the dot-format Java package name, for example, com.sybase.test.corba.

   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:

   • java, if specifying the package for CORBA stubs.

   • ejb, if specifying the package for EJB stubs.

   • jdbc, if specifying the package for Jaguar 1.1 client stubs.

   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.

Creating 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.

Editing 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.

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:

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:

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.

Creating 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.

Editing 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:

• InterfaceName is the name of the interface.

• operations is a zero or more of IDL operation declarations. You can enter operations directly as IDL, or use EAServer Manager to define them graphically (see “Operation declarations”).

• BaseInterface, BaseInterface2, and so forth form an optional list of existing interfaces from which the new interface inherits definitions. If a new interface inherits from other existing interfaces, the existing interfaces that are inherited from are referred to as base interfaces, and the new interface is referred to as a derived interface.

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:

• Operations and attributes cannot be redefined in the new interface.

• Operation and attribute names defined in base interfaces must be unique. For example, if a method is defined in both interface A and interface B, you cannot define a new interface that inherits from both B and A.

• Exceptions, constants, and types from a base interface can be redefined in the derived interface.

• References to type names, exception names, and constant names that are used in multiple derived interfaces must be made unambiguous by prefixing references with the name of the interface that contains the definition of interest. For example, if the constant MAX is defined in both A and B, then A::MAX refers to the definition in A, and B::MAX refers to the definition in B.

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:

• returnType is either a valid IDL datatype or void to indicate that the operation does not return a value. “Datatypes for parameters and return values” discusses datatypes in detail.

• opName is the name of the operation. Sybase recommends operation names begin with a lowercase letter. Names in the same interface must be unique with respect to case, and capitalization of a name must be consistent wherever it is used.

  IDL operation names cannot be overloaded (that is, redeclared with the same return type and different parameter lists). However, you can define IDL operations that map to overloaded C++ or Java methods. To do so, create operation names by appending two underscores and a unique suffix to the method name that will be overloaded. EAServer strips the suffix when generating C++ or Java interface definitions. For example, consider the following IDL:

  void ov1__double(in double d);
  void ov1__string(in long l);
  

  When mapped to C++ or Java, these operations translate to the following overloaded methods:

  void ov1(double d);
  void ov1(long l);
  

• parameterList is an optional parameter list enclosed in parentheses. The list (but not the parentheses) can be omitted to indicate that the operation takes no parameters. Otherwise, add datatypes and parameter names as shown below:

  void myMethod 
  ( 
  qual1 type1 param1, 
  qual2 type2 param2, 
  ...
  );
  

  where:

  • qual1, qual2, and so forth are one of the argument modes in, inout, or out. Use in for parameters that are input-only; no new value is returned when the operation completes. Use inout or out if the operation returns new values for the parameter. An inout parameter’s input value is meaningful; an out parameter’s input value is not.

  • type1, type2, and so forth are valid IDL type names (other than the CORBA::Any type). “Datatypes for parameters and return values” discusses datatypes in detail.

  • param1, param2, and so forth are parameter names.

• exceptionList is an optional list of user-defined exceptions. If the operation can throw user-defined exceptions, add a raises clause with a list of the IDL user-defined exception names that the operation can throw, as shown below:

  void myMethod ( in int n ) 
       raises ( Exception1, Exception2, ... );
  

  If the operation can throw only CORBA standard exceptions, omit the raises clause. For more information, see “User-defined exceptions”.

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.

Attributes are declared as shown below:

[ readonly ] attribute TypeSpec name;

where

• readonly is an optional keyword specifying that the attribute can be retrieved but cannot be set.

• TypeSpec is the name of a standard or user-defined type. “Datatypes for parameters and return values” describes datatypes in detail.

• name is the attribute name.

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);

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

• User-defined IDL datatypes

• Java class names used as IDL datatypes

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:

• Arrays are not yet supported. You can use sequences instead.

• The CORBA::Any type is not supported.

• constant declarations are supported.

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:

• The type is declared in another interface.

• The type is declared in another module.

• The type has the same local-scope name as a type declared in the interface or module that contains the operation.

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:

• The class containing the type name is in the CLASSPATH environment variable both when the interface is defined and when the server is run.

• At run time, you specify a class instance that is serializable. That is, a class must implement the java.io.Serializable interface or inherit from another class that does so, and an interface must extend the java.io.Serializable interface. If the instance is not serializable, the call fails with a CORBA::MARSHALL exception.

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

• Only Java components can implement the method and only Java clients can invoke the method.

• Only in parameters and return values can be declared with Java class names.

• Java datatypes are not marshaled as efficiently as an equivalent IDL datatype. Marshaling is the process of reading and writing parameters and return values from the network. More bytes are required to marshal values defined with a Java datatype than to marshal an equivalent IDL type. Consequently, invocations of a method defined with Java datatypes are slower than invocations of an equivalent method defined with IDL datatypes.

• IDL that contains Java class names may not be portable to other CORBA client ORB implementations unless they offer this extension to standard CORBA IDL.

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”.

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.

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:

• Organize the modules so that one module is declared per file, and each file has the same name as the module it declares.

  For example, module MyModule should be declared in the file MyModule.idl. Copy the files to the EAServer Repository subdirectory and restart the server. If the file contains no syntax errors, its declarations will be added to the EAServer Manager IDL folder. If the file does contain syntax errors, the server will log the errors during start-up and the module’s declarations will not be added to the IDL repository.

• Create a new module in EAServer Manager, as described in “Creating and editing IDL modules, interfaces, and types”.

  While the new module declaration is displayed in EAServer’s IDL editor, open the module to be imported in another text editor. Copy and paste the text of the module to be imported into the EAServer IDL editor.

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.