Chapter 6 Defining Component Interfaces
Jaguar stores all component interfaces in Interface Definition Language (IDL) modules. In Jaguar Manager, the IDL folder displays all modules available in Jaguar's interface repository.
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
Jaguar 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.
Defining new IDL modules
Specifying Java package mappings for IDL modules
idl-module=dotty-packageWhere:
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").
Jaguar Manager 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,
Jaguar Manager will report errors for any unresolved type references.
Editing IDL types, exceptions,
and interfaces
To edit or delete a type, exception, or interface:
Unreferenced IDL definitions
The interfaces, types and exceptions associated with a component
are not deleted when you delete the component from Jaguar manager.
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.
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:
Interfaces can be added in Jaguar 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:
Supported preprocessor directives
No IDL preprocessor directives other than #include
are
supported.
Creating new interfaces in Jaguar Manager:
Editing an existing interface:
Interfaces are declared as shown below:
interface InterfaceName [: BaseInterface1, BaseInterface2, ...] {
operations
};
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.
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, or by deploying from Sybase PowerJ.
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", Jaguar Manager adds this directive. The format is:
** <!-- home -->
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 ... ) ] ;
void ov1__double(in double d);
void ov1__string(in long l);
void ov1(double d);
void ov1(long l);
void myMethod
(
qual1 type1 param1,
qual2 type2 param2,
...
);
void myMethod ( in int n )
raises ( Exception1, Exception2, ... );
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;
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 Jaguar Manager. Use the IDL editor to view attribute
definitions.
To define parameter and return value datatypes, you can use Jaguar's predefined IDL datatypes or your own user-defined IDL types. In addition, Jaguar extends IDL to allow the use of Java class names. The sections below describe each option in detail.
Predefined IDL datatypes Jaguar 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.
Jaguar Manager's Method Properties dialog box displays the predefined datatypes in the drop-down lists for Parameter and Return types. "Predefined datatypes" lists Jaguar'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 Jaguar server installation. (Or, load the main Jaguar 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 Jaguar'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 Jaguar 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 Jaguar'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 Jaguar Manager types:
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".
Note
User-defined exceptions are not supported by ActiveX components
and clients.
Jaguar 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. Jaguar 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. Jaguar Manager treats any C-style comment as an IDL documentation comment. However, when you save in the IDL Editor window, Jaguar Manager reformats all C-style comments to match this example's spacing convention.
Stub 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.
HTML documentation is not generated automatically. You must use Jaguar Manager to create or update documentation for new or changed IDL modules. In Jaguar 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 Jaguar interface repository, generate HTML for any server. To selectively update documentation for interfaces used by components, generate HTML for a component or package; Jaguar 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.
Jaguar 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 Jaguar server's host name and yourport is the HTTP port number.
You can import interfaces defined in CORBA IDL into the Jaguar 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 Jaguar Repository subdirectory and restart Jaguar server if it is running.
You can repeat the procedures above to redefine existing IDL definitions.
| Copyright © 2000 Sybase, Inc. All rights reserved. |
| |