Version 7.3.

EntireX Enterprise JavaBeans Wrapper

This document applies to EntireX Communicator Version 7.3.2 and to all subsequent releases. Specifications contained herein are subject to change and these changes will be reported in subsequent release notes or new editions. Copyright Software AG 1997-2007. All rights reserved. The name Software AG and/or all Software AG product names are either trademarks or registered trademarks of Software AG. Other company and product names mentioned herein may be trademarks of their respective owners.

EntireX Enterprise JavaBeans Wrapper

EntireX Enterprise JavaBeans Wrapper

Table of Contents
EntireX Enterprise JavaBeans Wrapper . . . . . . EntireX Enterprise JavaBeans Wrapper . . . . . . Introduction to the EntireX Enterprise JavaBeans Wrapper . Introduction to the EntireX Enterprise JavaBeans Wrapper . . Using the EntireX Enterprise JavaBeans Wrapper . . . . Using the EntireX Enterprise JavaBeans Wrapper . . . . Generation Process . . . . . . . . . . Default Properties for the IDL File . . . . . . Generated Files . . . . . . . . . . Using the EJB Wrapper Interactively . . . . . . Using the EJB Wrapper Functions . . . . . . Setting/Modifying EntireX Enterprise JavaBeans Preferences Setting/Modifying IDL File Properties . . . . . Generated Classes and Interfaces . . . . . . . Home Interface . . . . . . . . . . Remote Interface . . . . . . . . . . EJB Class . . . . . . . . . . . . Mapper Class . . . . . . . . . . . Group Classes . . . . . . . . . . . Struct Classes . . . . . . . . . . . Input/Output Classes . . . . . . . . . Java RPC Client Stub . . . . . . . . . Example . . . . . . . . . . . . Delivered Example . . . . . . . . . . Using the EJB Wrapper in Command-line Mode . . . . Using the EJB Wrapper in Command-line Mode . . . . Software AG IDL to EJB Mapping . . . . . . . Software AG IDL to EJB Mapping . . . . . . . Mapping Software AG IDL Data Types to Java Data Types . Mapping Library Name and Alias . . . . . . . Mapping Program Name and Alias . . . . . . . Mapping Parameter Names . . . . . . . . Mapping Fixed and Unbounded Arrays . . . . . . Mapping Groups and Periodic Groups . . . . . . Mapping Structures . . . . . . . . . . Mapping the Direction Attribute IN, OUT, and INOUT . . Writing Applications - EntireX Enterprise JavaBeans Wrapper . Writing Applications - EntireX Enterprise JavaBeans Wrapper . Programming a Client Application . . . . . . . Locate the home interface . . . . . . . . Create an enterprise bean instance . . . . . . Invoke the mapped EntireX RPC method . . . . . Compiling and Running the Client Application . . . . Controlling Applications - EntireX Enterprise JavaBeans Wrapper Controlling Applications - EntireX Enterprise JavaBeans Wrapper Environment Entries to Control EJB . . . . . . Using Location Transparency and Enterprise JavaBeans . . Using Security/Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1 2 2 3 3 4 4 4 6 6 15 18 24 24 24 25 25 25 25 25 25 25 26 27 27 30 30 31 32 32 33 33 33 34 34 35 35 35 35 35 35 36 37 37 38 39 39

EntireX Enterprise JavaBeans Wrapper

EntireX Enterprise JavaBeans Wrapper

Using Natural Security . . . . . . . . . Using Compression . . . . . . . . . . Using Internationalization with EJB Wrapper . . . . Tracing . . . . . . . . . . . . . Deployment with an Application Server . . . . . . Deployment with SUN J2EE . . . . . . . Deployment with BEA WebLogic . . . . . . Deployment with JBoss . . . . . . . . . Deployment with a WebSphere Application Server under UNIX

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

40 . 40 . 41 . 41 . 42 . 42 . 45 . 46 . 46 .

ii

EntireX Enterprise JavaBeans Wrapper

EntireX Enterprise JavaBeans Wrapper

EntireX Enterprise JavaBeans Wrapper

The EntireX Enterprise JavaBeans Wrapper enables Java components to access an EntireX RPC server using Enterprise JavaBeans. This is accomplished by mapping RPC server libraries to EJB stateful session beans. A remote procedure call will be mapped to a method of the corresponding Enterprise JavaBeans. The Java components can use the logic implemented in the libraries of the existing RPC servers, or they can implement new logic on the application server side, using parts of the old logic. Introduction Using Provides an introduction to EntireX Enterprise JavaBeans Wrapper functionality. Describes how to use the EntireX Enterprise JavaBeans Wrapper: the generation process; using the EJB Wrapper interactively; provides a list of the files and classes generated by the workbench from the Software AG IDL file sources. Using the EJB Wrapper in command-line mode. Describes mapping Software AG IDL data types to Java data types. Describes the EJB Wrapper: programming a client application; compiling and running the client application. Describes the environment entries to control EJB. Describes how to use location transparency, security/encryption, Natural Security, compression, internationalization; tracing; and deployment with an application server.

Command-line mode IDL to EJB Mapping Writing Applications Controlling Applications

Introduction to the EntireX Enterprise JavaBeans Wrapper

EntireX Enterprise JavaBeans Wrapper

Introduction to the EntireX Enterprise JavaBeans Wrapper

The EntireX Enterprise JavaBeans Wrapper enables Java components to access an EntireX RPC server using Enterprise JavaBeans. This is accomplished by mapping RPC server libraries to EJB stateful session beans. A remote procedure call will be mapped to a method of the corresponding Enterprise JavaBeans. The Java components can use the logic implemented in the libraries of the existing RPC servers, or they can implement new logic on the application server side, using parts of the old logic.

EntireX Enterprise JavaBeans Wrapper

Using the EntireX Enterprise JavaBeans Wrapper

Using the EntireX Enterprise JavaBeans Wrapper

This chapter covers the following topics: Generation Process Using the EJB Wrapper Interactively Generated Classes and Interfaces Delivered Example

Using the EntireX Enterprise JavaBeans Wrapper

EntireX Enterprise JavaBeans Wrapper

Generation Process
To generate the Java EnterpriseBeans (EJB) source code, use the EntireX Workbench. This can be done interactively with the Graphical User Interface of the EntireX Workbench. The generation is controlled by the following properties:

Default Properties for the IDL File

Description Broker ID Server class Service class Service name Package name Package name prefix Data Type String String String String String String Default Value Localhost:1971 RPC SRV1 CALLNAT IDL file name without extension empty string

Generated Files
During the generation process for each library with the name <libname> the following interfaces and classes source files are created in the subdirectory EJB of the home directory of the <name>.idl file. The interfaces are created in the subdirectory: <Package Name Prefix><Package Name><file.separator>interfaces. They will be a component of the package: <Package Name Prefix><Package Name>.interfaces Naming Conventions EJB<libname>.java EJB<libname>Home.java The EJB classes will be created in the subdirectory: <Package Name Prefix><Package Name><file.separator>ejb They will be a component of the package: <Package Name Prefix><Package Name>.ejb Description The remote interface The home interface

EntireX Enterprise JavaBeans Wrapper

Using the EntireX Enterprise JavaBeans Wrapper

Naming Conventions EJB<libname>Bean.java

Description The enterprise bean class

<libname><innerclassname>.java Serializable classes for Software AG IDL groups/structs <libname><progname>Input.java Serializable holder class for all IN and IN/OUT parameters of the program
<libname><progname>Output.java Serializable holder class for all OUT and IN/OUT parameters of the program

<libname>Mapper.java

Mapper class

To build the jar files for the different application servers we generate an ant script which uses the xdoclet tool. This file will be generated in the EJB subdirectory: <Package Name Prefix><Package Name>.xml If the package prefix/name contains dots, subdirectories will be created, e.g., abc.def.library will become abc/def/library/...

Using the EntireX Enterprise JavaBeans Wrapper

EntireX Enterprise JavaBeans Wrapper

Using the EJB Wrapper Interactively

Using the EJB Wrapper Functions
To use the EJB Wrapper functions 1. Open the EntireX Workbench. 2. Create a new Java Project (e.g.: "EJB"), using File > New > Project.

EntireX Enterprise JavaBeans Wrapper

Using the EntireX Enterprise JavaBeans Wrapper

3. Add the EntireX classes to the build path of the project (entirex.jar).

Using the EntireX Enterprise JavaBeans Wrapper

EntireX Enterprise JavaBeans Wrapper

EntireX Enterprise JavaBeans Wrapper

Using the EntireX Enterprise JavaBeans Wrapper

4. Add the Enterprise JavaBeans classes to the build path of the project (e.g.: j2ee.jar).

Using the EntireX Enterprise JavaBeans Wrapper

EntireX Enterprise JavaBeans Wrapper

10

EntireX Enterprise JavaBeans Wrapper

Using the EntireX Enterprise JavaBeans Wrapper

5. Import the IDL file into the project.

11

Using the EntireX Enterprise JavaBeans Wrapper

EntireX Enterprise JavaBeans Wrapper

12

EntireX Enterprise JavaBeans Wrapper

Using the EntireX Enterprise JavaBeans Wrapper

13

Using the EntireX Enterprise JavaBeans Wrapper

EntireX Enterprise JavaBeans Wrapper

6. Activate the example.idl file.

14

EntireX Enterprise JavaBeans Wrapper

Using the EntireX Enterprise JavaBeans Wrapper

Setting/Modifying EntireX Enterprise JavaBeans Preferences

To set/modify the preferences 1. Display the Preferences window.

15

Using the EntireX Enterprise JavaBeans Wrapper

EntireX Enterprise JavaBeans Wrapper

16

EntireX Enterprise JavaBeans Wrapper

Using the EntireX Enterprise JavaBeans Wrapper

17

Using the EntireX Enterprise JavaBeans Wrapper

EntireX Enterprise JavaBeans Wrapper

Setting/Modifying IDL File Properties

To set/modify the properties 1. Display the Properties window; use either the pop-up menu or, from the File menu, choose Properties.

18

EntireX Enterprise JavaBeans Wrapper

Using the EntireX Enterprise JavaBeans Wrapper

2. In the Properties window choose the EntireX Communicator tab. Here it is possible to modify the common defaults properties for the IDL file.

19

Using the EntireX Enterprise JavaBeans Wrapper

EntireX Enterprise JavaBeans Wrapper

3. Choose the Enterprise EJB Wrapper tab. Here it is possible to modify the defaults (refer to the table Default Properties for the IDL File, below).

20

EntireX Enterprise JavaBeans Wrapper

Using the EntireX Enterprise JavaBeans Wrapper

4. Confirm the entries with OK. To generate the EJB sources 1. From the context menu, choose Generate EJB from Software AG IDL > Enterprise JavaBean 2.0.

21

Using the EntireX Enterprise JavaBeans Wrapper

EntireX Enterprise JavaBeans Wrapper

2. All generated EJB sources are in the subdirectory EJB of the home directory of the IDL file.

22

EntireX Enterprise JavaBeans Wrapper

Using the EntireX Enterprise JavaBeans Wrapper

23

Using the EntireX Enterprise JavaBeans Wrapper

EntireX Enterprise JavaBeans Wrapper

Generated Classes and Interfaces

The workbench generates the following interfaces and classes from the Software AG IDL file sources.

Home Interface
The generated home interfaces EJB<libname>Home.java contain the create methods. These methods can be called by an EJB Client.

create()
EJB<libname> create()

Calling this method creates an EJB with the default settings.

create( String user )

EJB<libname> create(String user)

where: String user is the Broker user name Calling this method creates an EJB with the default settings except for the user name.

create( String user, String password )

EJB<libname> create(String user,String password)

where: String user is the Broker user name and String password the Broker user password Calling this method creates an EJB with the default settings except for the user name and the password.

Remote Interface
The generated remote interfaces EJB<libname>.java contain the customer methods. For each RPC program a customer method is generated with the following naming conventions.

<libname><program>Output <program> (<libname><program>Input input)

where: Output is the output object and Input is the input object These methods can be called by an EJB Client.

24

EntireX Enterprise JavaBeans Wrapper

Using the EntireX Enterprise JavaBeans Wrapper

EJB Class
The generated EJB class EJB<libname>Bean.java extends <libname>Mapper.java class. Bean implements the EJB session bean and controls the EntireX RPC communication.

Mapper Class
The generated <libname>Mapper.java class extends the Java RPC client stub <libname>.java. It implements a method for each RPC Program. Methodname is <program>. The method has one parameter, an instance of <libname><progname>Input.class. The return value of the method is an instance of <libname><progname>Output.class.

Group Classes
The group classes are serializable representations of the inner classes of the groups of the RPC library, filename is <libname><progname><innerclassname>.java. The class contains all parameters of the group.

Struct Classes
The struct classes are serializable representations of the inner classes of the structs of RPC library, filename is <libname><innerclassname>.java. The class contains all parameters of the struct.

Input/Output Classes
These classes are serializable representations of all in, out, in/out parameters of RPC program. The filename of the input classes is <libname><progname>Input.java, it holds all in and in/out parameters of the program. The filename of the output classes is <libname><progname>Output.java, it holds all out and in/out parameters of the program.

Java RPC Client Stub

The generated Java RPC Stub <libname>.java extends com.softwareag.entirex.aci.RPCService class. It is the connecting link between the EJB and the EntireX server.

Example

25

Using the EntireX Enterprise JavaBeans Wrapper

EntireX Enterprise JavaBeans Wrapper

Delivered Example
An Example is delivered in the directory: For Windows: <EntireX Home>\Examples\EJB Wrapper For UNIX: EXXDIR/$EXXVERS/examples/ejb_wrapper See the README.TXT.

26

EntireX Enterprise JavaBeans Wrapper

Using the EJB Wrapper in Command-line Mode

Using the EJB Wrapper in Command-line Mode

See Using EntireX Workbench from a Command Line for the general command-line syntax. The table below shows the command-line options for the EJB Wrapper. The behavior of the generation in command-line mode depends on the IDL file: If the IDL file is part of the workspace, the generator generates the sources, controlled by the properties of the IDL file. The properties can be overwritten by the command-line options. If the IDL file is not part of the workspace but part of the file system, the generator creates the subdirectory EJB in the parent directory of the IDL file and generates the source files into this subdirectory. The generation can be controlled by the command-line options.

27

Using the EJB Wrapper in Command-line Mode

EntireX Enterprise JavaBeans Wrapper

Command

Option

Default Value localhost:1971 null EjbUserName no 0

Description Broker identification Broker user password Broker user ID Compression level (No,Yes,0-9) Encryption level (0,1,2) Locator service configuration Locator service initialization Name of set of rules Java ACI trace file Logical Broker identifier Name of Logical service Logon to Natural Package name for EJB classes Package name prefix RPC user password RPC user ID Use EntireX security Service name (class/server/service) Folder of the generated classes Java ACI trace level (0,1,2) Send default codepage to the broker Enable EJB log information

-ejb:generate -broker

-brokerpassword -brokeruser -compresslevel -encryption

-locationtransparencyconfig null -locationtransparencyinit null

-locationtransparencysetname null

-log -logicalbroker -logicalservice -logonnaturalsecurity -package -packageprefix -rpcpassword -rpcuser -security -server -sourcefolder -trace -usecodepage -verbose

null null null false IDL file name without extension null null null false RPC/SRV1/CALLNAT <IDL file parent directory>/EJB 0 false false

Example
<workbench> -ejb:generate /Demo/Example.idl -sourcefolder /Demo/src1

where <workbench> is a placeholder for the actual Workbench starter as described under Using EntireX Workbench from a Command Line.

28

EntireX Enterprise JavaBeans Wrapper

Using the EJB Wrapper in Command-line Mode

The name of the IDL file and the source folder include the project name. In the example, the project Demo is used. If the first part of the IDL file name is not a project name in the current workspace, the IDL file name is used as a file name in the file system. Thus, the IDL files do not need to be part of an Eclipse project. If the source folder does not exist in the workspace but the first part describing the project exists, the source folder is created. If the IDL file is located outside the Eclipse workspace, the source folder is also a folder in the file system. Status and processing messages are written to standard output (stdout), which is normally set to the executing shell window.

29

Software AG IDL to EJB Mapping

EntireX Enterprise JavaBeans Wrapper

Software AG IDL to EJB Mapping

This chapter covers the following topics: Mapping Software AG IDL Data Types to Java Data Types Mapping Library Name and Alias Mapping Program Name and Alias Mapping Parameter Names Mapping Fixed and Unbounded Arrays Mapping Groups and Periodic Groups Mapping Structures Mapping the Direction Attribute IN, OUT, and INOUT

30

EntireX Enterprise JavaBeans Wrapper

Software AG IDL to EJB Mapping

Mapping Software AG IDL Data Types to Java Data Types

In the table below, the following metasymbols and informal terms are used for the Software AG IDL. The metasymbols [ and ] surround optional lexical entities. The informal term number (or number [.number]) is a sequence of numeric characters, for example 123. Software AG IDL Anumber AV AV[number] B number BV BV[number] D F4 F8 I1 I2 I4 K number KV KV[number] L Description Alphanumeric Alphanumeric variable length Alphanumeric variable length with maximum length Binary Binary variable length Binary variable length with maximum length Date Floating point (small) Floating point (large) Integer (small) Integer (medium) Integer (large) Kanji Kanji variable length Kanji variable length with maximum length Logical Java Data Types String String String byte[] byte[] byte[] java.util.Date float double byte short int String String String Boolean
java.math.BigDecimal 4 java.math.BigDecimal 4 java.math.BigDecimal 4 java.math.BigDecimal 4
Note

1, 3

1 1, 6

1 5 2 2

N number [.number] Unpacked decimal NU number [.number] P number [.number] PU number [.number] T U number UV UV number Unpacked decimal unsigned Packed decimal Packed decimal unsigned Time Unicode Unicode variable length Unicode variable length with maximum length

java.util.Date String String String

5 7 7 7

31

Software AG IDL to EJB Mapping

EntireX Enterprise JavaBeans Wrapper

Notes: 1. The field length is given in bytes. 2. If floating point data types are used, errors due to rounding can occur. Therefore, the values of sender and receiver might differ slightly. 3. If you use the value null (null pointer) as an input parameter (for IN and INOUT parameters) for type A, a blank string will be used. 4. If you use the value null (null pointer) as an input parameter (for IN and INOUT parameters) for types N/P, the value 0 (or 0.0) will be used. 5. If you use the value null (null pointer) as an input parameter (for IN and INOUT parameters) for types D/T, the current date/time will be used. You change this with the property entirex.marshal.date. Setting entirex.marshal.date=null will map the value null to the invalid date 0000-01-01 of the RPC marshalling. This is the invalid date value in Natural, too. With this setting the invalid date as an output parameter will be mapped to null. The default is to map the invalid date to 0001-01-01. 6. If you use the value null (null pointer) as an input parameter (for IN and INOUT parameters) for type B, all binary values will be set to zero. 7. The length is given in 2-byte Unicode code units following the Unicode standard UTF-16. The maximum length is 805306367 code units. Please note also hints and restrictions on the Software AG IDL Data types valid for all programming language bindings. See Interface Definition Language for EntireX RPC, Software AG IDL Data Types.

Mapping Library Name and Alias

The library name in the library-definition of the Software AG IDL File is mapped to the class name of the generated Enterprise JavaBean. For the Enterprise JavaBean, the names of the classes have the format library-name Bean. The special characters # and - in the library name are replaced by the character _. If there is an alias for the library name in the library-definition, this alias is used "as is" to form the Enterprise JavaBean class name. Therefore, this alias must be a valid Java class name. Example: library name Hu#G-O is converted to EJBHu_g_oBean.class The library name is sent - without changes - to the server. The library alias is never sent to the server. In the RPC server the library name sent may be used to locate the target server.

Mapping Program Name and Alias

The program name in the program-definition of the Software AG IDL File is mapped to method names within the generated Enterprise JavaBeans. To adhere to Java naming conventions the program name is converted to lowercase. The special characters # and - in the program name are replaced by the character _.

32

EntireX Enterprise JavaBeans Wrapper

Software AG IDL to EJB Mapping

If there is an alias for the program name in the program-definition, this alias is used "as is" for the method name. Therefore, this alias must be a valid Java method name. The program name is converted to uppercase before it is sent to the server. The program alias is never sent to the server. The program name sent to the RPC server is used to locate the target server.

Mapping Parameter Names

The parameter names are mapped to fields inside the serializable input and output classes (see Mapping the Direction Attribute IN, OUT, and INOUT). The name of the input class is made up of the library-name and the program-name <library-name><program-name> Input and for the output class is <library-name><program-name> Output. Example:

public class LibPgmInput implements Serializable { public String myInputString; public String myOutInString; }

public class LibPgmOutput implements Serializable { public String myOutputString; public String myOutInString; }

Mapping Fixed and Unbounded Arrays

Arrays in the IDL file are mapped to Java arrays. If an array value does not have the correct number of dimensions or elements, this will result in a NullPointerException or an ArrayIndexOutOfBoundsException. If you use the value null (null pointer) as an input parameter (for IN and INOUT parameters), an array will be instantiated.

Mapping Groups and Periodic Groups

Groups are mapped to serializable classes. The class name is the <library name><program name> <parameter name>, For example, the following Software AG IDL
Library Lib1130 Is Program X201G0 Is Define Data Parameter 1 MyGroup 2 MyLong (I4) 2 MyFloat (F4) 1 MyGroupAsString (A253) 1 function_result (I4) Out End-Define

33

Software AG IDL to EJB Mapping

EntireX Enterprise JavaBeans Wrapper

is mapped to the class

public class Lib1130X201g0MyGroup implements Serializable { public int mylong; public float myfloat; }

Mapping Structures
Structures are mapped to serializable classes. The class name is the <library name><struct name>.

Mapping the Direction Attribute IN, OUT, and INOUT

IDL syntax allows you to define parameters as IN parameters, OUT parameters, or INOUT parameters (the default). This specification of the direction is reflected in the generated Enterprise JavaBeans as follows: IN parameters are sent from the RPC client to the RPC server. IN parameters are collected in the serializable input class (see Mapping Parameter Names). OUT parameters are sent from the RPC server to the RPC client. OUT parameters are collected in the serializable output class (see Mapping Parameter Names). INOUT parameters are sent from the RPC client to the RPC server and then back to the RPC client. INOUT are collected into both classes the serializable input class as well as into the serializable output class. (see Mapping Parameter Names). Note: Only the direction information of the top-level fields (level 1) is relevant. Group fields always inherit the specification from their parent. Any different specification is ignored. See the attribute-list for the syntax on how to describe attributes in the Software AG IDL file and refer to the direction attribute.

34

EntireX Enterprise JavaBeans Wrapper

Writing Applications - EntireX Enterprise JavaBeans Wrapper

Writing Applications - EntireX Enterprise JavaBeans Wrapper

This chapter covers the following topics: Programming a Client Application Compiling and Running the Client Application

Programming a Client Application

To program a client which uses an enterprise bean, perform the following tasks:

Locate the home interface

Create the initial context
Context initial=new InitialContext();

Get the object bound to the JNDI name EJBExample

Context myEnv=(Context) initial.lookup("EJBExample");

Narrow the reference to an EJBExampleHome object

EJBExampleHome home=(EJBExampleHome)PortableRemoteObject.narrow(objref,EJBExampleHome.class)

Create an enterprise bean instance

Declare the bean object
EJBExample ejbExample=null;

Create the bean object with default settings

ejbExample=home.create();

Or create the bean object with default settings except for the user name
ejbExample=home.create("myUserName");

Or create the bean object with default settings except for the user name and password
ejbExample=home.create("myUserName","myPassword");

Invoke the mapped EntireX RPC method

Create the input and output objects

35

Writing Applications - EntireX Enterprise JavaBeans Wrapper

EntireX Enterprise JavaBeans Wrapper

ExampleHelloInput input=new ExampleHelloInput(); ExampleHelloOutput output=new ExampleHelloOutput();

Set the input values

input.client="I am the user"; input.mail="This is my mail: 0123456789";

Show the input values

System.out.println( "hello client >>> "+intput.clientl ); System.out.println( "hello mail >>> "+intput.mail );

Call the EntireX RPC method

output = ejbExample.hello(input);

Show the output value

System.out.println( "hello mail <<< "+output.mail );

Remove the bean object

ejbExample.remove();

Compiling and Running the Client Application

Compile the client with the client JAR. It will be packed by the Application Server (SUN) or by the ant script. Get the build.xml file from the example directory. Set antfile to your current xml file. Replace Client.java by your client class name. To run the client Enter

ant sun_run_client

Or:

ant bea_run_client

Or:

ant jboss_run_client

36

EntireX Enterprise JavaBeans Wrapper

Controlling Applications - EntireX Enterprise JavaBeans Wrapper

Controlling Applications - EntireX Enterprise JavaBeans Wrapper

This chapter covers the following topics: Environment Entries to Control EJB Using Location Transparency and Enterprise JavaBeans Using Security/Encryption Using Natural Security Using Compression Using Internationalization with EJB Wrapper Tracing Deployment with an Application Server

37

Controlling Applications - EntireX Enterprise JavaBeans Wrapper

EntireX Enterprise JavaBeans Wrapper

Environment Entries to Control EJB

To define the behavior of the EJB Use the following environment entries Entry Name Broker Server Logical Broker Logical Service Location Transparency Setname Default Value Localhost:1971 Description Broker ID

RPC/SRV1/CALLNAT Service name (class/server/service)

null null null

Logical Broker identifier Name of logical service Name of set of rules Locator service initialization Locator service configuration Broker user ID Broker user password Compression level (No,Yes,0-9) Use codepage Use EntireX security Encryption level (0,1,2) Use Natural security RPC user ID RPC user password Bean log information Java ACI trace level (0,1,2) Java ACI trace file

Location Transparency Initialization null Location Transparency Configuration User Password Compression Level Codepage Security Encryption Natural Security RPC User RPC Password Verbose Trace Logfile null EjbUserName null no false false 0 false null null false 0 null

38

EntireX Enterprise JavaBeans Wrapper

Controlling Applications - EntireX Enterprise JavaBeans Wrapper

Using Location Transparency and Enterprise JavaBeans

Location Transparency introduces the concept of logical services translated into real services. The Enterprise JavaBeans can change the real Broker ID and class/server/service entries without having to configure anything or change client and/or server programs. To use Location Transparency you must setup an LDAP directory service. This locator service is initialized implicitly with the file XDS.ini. Specify the location of this file in the environment entry Location Transparency Initialization. For details on XDS.ini see Configuration of Location Transparency Agent using System Management Hub under UNIX |Windows. As an alternative, a string with the parameters of the LDAP directory may be used. This string can be given by the environment entry Location Transparency Configuration. For the syntax of this string, see the description of class LocationTransparencyService.

Notes:
1. On UNIX, one of the environment entries Location Transparency Configuration or Location Transparency Initialization must be used. 2. On Windows, these environment entries may be omitted when EntireX is installed in the folder C:\Program Files\Software AG\EntireX. To use Logical Service with DefaultSet 1. Set up LDAP directory service. 2. Set environment entry name Logical Service to a valid logical service name. To use Logical Broker with DefaultSet 1. Set up LDAP directory service. 2. Set environment entry name Logical Broker to a valid logical broker identifier. To change the rules set 1. Set up LDAP directory service. 2. Set environment entry name Location Transparency Setname to a valid set name.

Using Security/Encryption
To use EntireX Security Set entry name Security to "true", User to the current user and Password to the current password. With these settings the Broker checks user and password.

39

Controlling Applications - EntireX Enterprise JavaBeans Wrapper

EntireX Enterprise JavaBeans Wrapper

To use EntireX Security with encryption level broker Set entry name Security to "true", Encryption equals 1, User to the current user and Password to the current password. With these settings the Broker checks user and password, the data of send and receive calls are encrypted from the application server to the Broker. To use EntireX Security with encryption level target Set entry name Security to "true", Encryption equals 2, User to the current user and Password to the current password. With these settings the Broker checks user and password, and the data of send and receive calls are encrypted from the application server to the RPC server.

Using Natural Security

To use Natural Security Set entry name Natural Security to "true", User to the current Natural user and Password to the current Natural password. With these settings the Broker checks Natural user and Natural password. If you want to use EntireX Security and Natural Security and the Natural Security user name is not the same as the EntireX Security user name, set entry name RPC User to the current Natural user. If the Natural Security password is the same as the EntireX Security password, set entry name RPC User to the current Natural user.

Using Compression
To use EntireX Compression Set entry name Compression level to one of the following values: Value 9 1 Y(es) or 6 8 N(o) or 0 Description Best Compression Best Speed Default Compression Deflated No Compression Data Type string string string string string

40

EntireX Enterprise JavaBeans Wrapper

Controlling Applications - EntireX Enterprise JavaBeans Wrapper

Using Internationalization with EJB Wrapper

It is assumed that you have read the introductory document Internationalization with EntireX and are familiar with the various internationalization approaches. EntireX Java components use the codepage configured for the Java Virtual Machine (JVM) to convert the Unicode (UTF-16) representation within Java to the multi-byte or single-byte encoding sent/received to/from the broker by default. This codepage is also transferred as part of the locale string to tell the broker the encoding of the data if communicating with a broker version 7.2.x and above. To change the default, see your JVM documentation. On some JVM implementations, it can be changed with the file.encoding property. On some UNIX implementations, it can be changed with the LANG environment variable. Which encodings are valid depends on the version of your JVM. For a list of valid encodings, see Supported Encodings in your Java documentation. The encoding must also be a supported codepage of the broker, depending on the internationalization approach. With the entry name Codepage you can force a locale string to be sent if communicating with broker version 7.1.x and below. Set entry name Codepage to "true" for this purpose. not use a codepage other than the default encoding of the JVM.

Tracing
To switch on bean tracing Set entry name Verbose to "true". Some EJB-relevant information is written to the standard output of the application server. To switch on Java ACI tracing Set entry name Trace to "0","1","2" or "3". The output will be written to standard output. Trace Level 0 1 2 3 Description No trace output Trace all Broker calls and other major actions Dump the send-and-receive buffer Dump the buffers sent to the Broker and received from the Broker To write the trace information to a file

41

Controlling Applications - EntireX Enterprise JavaBeans Wrapper

EntireX Enterprise JavaBeans Wrapper

Set the entry name Logfile to the corresponding file.

Deployment with an Application Server

This section covers the following topics: Deployment with SUN J2EE Deployment with BEA WebLogic Deployment with JBoss Deployment with a WebSphere Application Server under UNIX Note: Version numbers to third-party products are listed centrally in the sectionEntireX Prerequisites. In the examples, notation such as nn or nnn refers to the two- or three-digit version numbers. Make sure that the application server can access the EntireX Java runtime, see Enterprise JavaBeans Wrapper - Hints for Application Servers under UNIX | Windows. For the compilation of the generated sources and the generation of the deployment descriptors we use ant and xdoclet. Load, install, and verify ant, see <cd-root>/share/3rdparty/ant nnn.zip or http://ant.apache.org. Load, install, and verify xdoclet, see <cd-root>/share/3rdparty/xdoc nnn.zip or http://sourceforge.net/projects/xdoclet. Windows users: If your path names or file names contain blanks, you have to use the short name notation without blanks, e.g.: Use C:\PROGRA~1\XYZ instead of C:\Program Files\xyz

Deployment with SUN J2EE

To compile the EJB and Client code in the IDL directory 1. You can use the build.xml file as a template, which is provided in the EJB example $EXXDIR/$EXXVERS/examples/ejb_wrapper. 2. Change the assignment antfile="example.xml" according to your own XML file name. 3. Adapt the basedir and the following properties in the build.xml file, for example
<project name="Example" default="all" basedir="."> <target name="init"> <property name="exx.classes" value="C:\PROGRA~1\SOFTWAR~1\ENTIREX\CLASSES\ENTIREX.JAR"/> <property name="ant.classes" value="C:\jakarta-ant-nn\lib\ant.jar"/> </target> <target name="sun_init" depends="init"> <property name="sun.home" value="C:\Sun\AppServer"/> </target>

42

EntireX Enterprise JavaBeans Wrapper

Controlling Applications - EntireX Enterprise JavaBeans Wrapper

4. Run the ant tool:

ant sun_compile

5. Start the application server: Programs >Sun Microsystems >J2EEnnSDK >Start Default Server. 6. Start SUNs deployment tool: Programs >Sun Microsystems >J2EEnnSDK >Deploytool. 7. Deploy the EJBExampleBean with SUNs deployment tool. 8. Create the J2EE application 1. Choose File >New >Application 2. Browse to the EJB directory and enter file name example.ear and enter New Application 3. Confirm with OK 9. Package the Enterprise Bean. 1. Choose File >New >Enterprise Bean. 2. Enter "EJBExample" in the JAR Display Name field. 3. Choose Edit. 4. Select and add the example directory and confirm with OK. 5. Select and add <Entirex Home Directory>\classes\entirex.jar 6. Choose Next. 7. In the Enterprise Bean Class field, select example.ejb.EJBExampleBean. 8. Select the Stateful button. 9. In the Remote Home Interface, selectexample.interfaces.EJBExampleHome. 10. In the Remote Interface, select example.interfaces.EJBExample. 11. Choose Next. 12. Choose Finish. 10. Package the J2EE Application Client 1. Choose File >New >Application Client

43

Controlling Applications - EntireX Enterprise JavaBeans Wrapper

EntireX Enterprise JavaBeans Wrapper

2. Enter "Client" in the Display Name field. 3. Choose Edit 4. Browse to the ejb_wrapper directory 5. Select and add the client.class and the example directory and confirm with OK 6. Choose Next 7. In the Main Class check box, select Client 8. Choose Next 9. Choose Finish 11. Specify the clients EJB reference 1. Select Client in the example tree 2. Select EJB Refs 3. Choose Add 4. Enter "EJBExample" in the Coded Name column 5. Select Session in the Type column 6. Select Remote in the Interface column 7. Enter "EJBExampleHome" in the Home Interface column 8. Enter "EJBExample" in the Local/Remote Interface column 9. Select the JNDI Name 10. Enter "EJBExample" 11. Confirm with OK 12. Switch on Verbose mode 1. Select EJBExample in the example tree 2. Select EJBExampleBean in the EJBExample tree 3. Choose the Env. Entries tab 4. Choose Add 5. Enter "Verbose" in the Coded Entry column 6. Select Boolean in the Type field

44

EntireX Enterprise JavaBeans Wrapper

Controlling Applications - EntireX Enterprise JavaBeans Wrapper

7. Select True in the Value field 13. Map the Enterprise Bean References. 1. Select example in the Applications tree 2. Choose Sun-specific Settings 3. Enter "EJBExample" in the JNDI Name fields 4. Choose Close 14. Deploy the application 1. Select example in the applications tree 2. Select Tools >Deploy 3. Select the check box Return Client Jar 4. Choose Next 5. Choose Finish You will find the following files in your EJB directory: example.ear exampleClient.jar

Deployment with BEA WebLogic

To deploy the EJB with BEA WebLogic 1. You can use the build.xml file as a template, which is provided in the EJB example $EXXDIR/$EXXVERS/examples/ejb_wrapper. 2. Change the assignment antfile="example.xml" according to your own XML file name. 3. Adapt the basedir and the following properties in the build.xml file, e.g.:
<project name="Example" default="all" basedir="."> <target name="init"> <property name="exx.classes" value="C:\PROGRA~1\Softwa~1\ENTIREX\CLASSES\ENTIREX.JAR"/> <property name="ant.classes" value="C:\jakarta-ant-nn\lib\ant.jar"/> <property name="xdoclet.home" value="C:\xdoclet-nnn\bin"/> </target> <target name="bea_init" depends="init"> <property name="log4j.classes" value="C:\xdoclet-nnn\samples\lib\log4j.jar"/> <property name="j2ee.classes" value="C:\bea\weblogicnnn\server\lib\weblogic.jar"/> <property name="weblogic.home" value="C:\bea\weblogicnnn"/> <property name="applications" value="D:\Tests\BEA_Weblogic\mydomain\applications"/> </target>

4. Package the EJB by entering

45

Controlling Applications - EntireX Enterprise JavaBeans Wrapper

EntireX Enterprise JavaBeans Wrapper

ant bea_package

5. Deploy the EJB by entering

ant bea_deploy

Deployment with JBoss

To deploy the EJB with JBoss 1. You can use the build.xml file as a template, which is provided in the EJB example $EXXDIR/$EXXVERS/examples/ejb_wrapper. 2. Change the assignment antfile="example.xml" according to your own XML file name. 3. Adapt the basedir and the following properties in the build.xml file, e.g.:
<project name="Example" default="all" basedir="."> <target name="init"> <property name="exx.classes" value="C:\PROGRA~1\Softwa~1\ENTIREX\CLASSES\ENTIREX.JAR"/> <property name="ant.classes" value="C:\jakarta-ant-nn\lib\ant.jar"/> <property name="xdoclet.home" value="C:\xdoclet-nnn\lib"/> </target> <target name="jboss_init" depends="init"> <property name="jboss.home" value="C:\jboss-nnn"/> </target>

4. Package the EJB by entering

ant jboss_package

5. Deploy the EJB by entering

ant jboss_deploy

Deployment with a WebSphere Application Server under UNIX

Note: The following description has been verified with the delivered EJB example and WebSphere 5 on RedHat Linux Advanced Server 2.1 for x86 and might be different for other WebSphere releases. The following steps are described in this section: Compiling the EJB Example Generating Code for Deployment Creating an Application Client Creating an Application

46

EntireX Enterprise JavaBeans Wrapper

Controlling Applications - EntireX Enterprise JavaBeans Wrapper

EJB Deployment

Compiling the EJB Example

To compile the example 1. You can use the build.xml file as a template, which is provided in the EJB example $EXXDIR/$EXXVERS/examples/ejb_wrapper. 2. Change the assignment antfile="example.xml" according to your own XML file name. 3. Adapt the basedir and the following properties in the build.xml file:
<project name="Example" default="all" basedir="/SAG/exx/vnnn/examples/ejb_wrapper"> <target name="init"> <property name="exx.classes" value="/SAG/exx/vnnn/classes/entirex.jar"/> <property name="ant.classes" value="/SAG/antnnn/lib/ant.jar"/> <property name="xdoclet.classes" value="/SAG/xdocnnn/lib/xdoclet.jar"/> </target> <target name="ibm_init" depends="init"> <property name="java.classes" value="/opt/jdknnn_06/lib/tools.jar"/> <property name="j2ee.classes" value="/opt/j2sdkeennn/lib/j2ee.jar"/> </target>

4. Compile the bean components:

ant -buildfile build.xml ibm_compile

5. Compile the client main program:

ant -buildfile build.xml ibm_compile_client

Generating Code for Deployment

To generate code for deployment 1. Start the Assembly tool of WebSphere:

/opt/WebSphere/AppServer/bin/assembly.sh

2. From the New tab choose EJB Module. In the left frame of the screen the types of beans belonging to the module are listed (Session Beans, Entity Beans, Message Driven Beans, etc.), while the right frame shows the properties. 3. Create a new deployment descriptor for the bean by selecting Session Beans and choosing New.

47

Controlling Applications - EntireX Enterprise JavaBeans Wrapper

EntireX Enterprise JavaBeans Wrapper

The window New Session Bean will be displayed. 4. In the tab General enter the EJBName, the EJB class, and in the Remote section Home and Interface:
EJB name: EJB class: Remote Home: Interface: EJBExampleBean example.ejb.EJBExampleBean example.interfaces.EJBExampleHome example.interfaces.EJBExample

5. In the tab Advanced choose session type Stateful. 6. In the tab Bindings set the JNDI Name JNDI name: EJBExample 7. Confirm with OK. 8. On the left screen choose Add Files. 9. Add all class files created by the EntireX Workbench EJB function and compile. Browse and select exx/vnnn/examples/ejb_wrapper and Add Client.class. Browse to exx/vnnn/examples/ejb_wrapper and choose EJB. Select example in the right window and choose Add. (it is important that the selected files have a path name such as example/ejb/file.class). 10. Add all class files of entirex.jar Browse to exx/vnnn/classes and choose entirex.jar. Select com, choose Add and OK (do not add the META-INF). Save the archive EJBExample.jar. 11. From the File menu, choose Generate Code for deployment... and then Generate Now. A file Deployed_EJBExample.jar will be generated. 12. Close the bean module.

Creating an Application Client

To create an application client 1. Create a new application client. From the File menu select New and choose Application Client. 2. Change the Display name and complete the text field Client in the Main class. 3. Select EJB References and choose New.

48

EntireX Enterprise JavaBeans Wrapper

Controlling Applications - EntireX Enterprise JavaBeans Wrapper

4. In the tab General enter the Bean name ejb/MyExample. 5. Obtain the environment naming context of the application client. (Further information on this item: The J2EE Tutorial - Coding the J2EE Application Client) 6. Enter the Home and Remote interface:
Name: ejb/MyExample Home: example.interfaces.EJBExampleHome Remote: example.interfaces.EJBExample

7. In the tab Bindings enter the JNDI name. JNDI name: EJBExample 8. Save the application client (ApplicationClient.jar).

Creating an Application
To create a new application 1. From the File menu select New and choose Application. 2. Change the Display name. 3. Select Application Clients and import ApplicationClient.jar. 4. Select EJB Module and import Deployed_EJBExample.jar. 5. Save the application as Application.ear.

EJB Deployment
To deploy the EJB 1. Open an Administration console in a Browser (http://localhost:9090/admin). 2. From the File menu select Applications and choose Install New Application and enter the path to your application (enter path to the file Application.ear). 3. Click Next. 4. Specify the prefix you have already chosen for the client application (etb/MyExample) and choose Do not override existing bindings. 5. Click Next. 6. Choose Enable class reloading and Next. 7. Verify the JNDI name and choose Next. 8. Choose EJB Module, Next and then Finish.

49

Controlling Applications - EntireX Enterprise JavaBeans Wrapper

EntireX Enterprise JavaBeans Wrapper

9. Save the configuration with Save to Master Configuration. 10. Choose Enterprise Applications and start the application.

50