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.
Choosing an interface name
Interface names are restricted as follows:
Interfaces within a module must have unique names, irrespective of case. That is, you cannot define MyInterface and Myinterface in the same module.
The interface cannot have the same name as the module that contains it.
Sybase recommends that you begin interface names with a capital letter, and operation names with a lowercase letter.
Creating new interfaces in EAServer Manager
Highlight the module’s icon and choose File | New IDL Entity.
Type the name of the new interface, choose Interface in the dropdown list of IDL entity types, and click Ok.
Click Ok.
EAServer Manager displays a new, blank interface in the IDL Editor window. Edit the declaration if needed.
When done, choose File | Save, then File | Exit to close the IDL Editor window.
Select the interface’s icon and choose File | Edit IDL.
EAServer Manager extracts the interface definition from the module and displays it in the IDL editor window.
Edit the declaration as needed.
When done, choose File | Save, then File | Exit to close the IDL Editor window.
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.
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.
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”.
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 not supported by ActiveX components and
clients.
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);
Currently, attributes do not do not display with a component’s
methods in EAServer Manager. Use the IDL editor to view attribute
definitions.
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:
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.
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”.
User-defined exceptions are not supported by ActiveX
components and clients.
