dev manual

Development Manual

SAP J2EE Engine 6.20

Development Manual SAP J2EE Engine 6.20

Contents

About This Manual ...............................................................................9 Target Audience and Prerequisites ....................................................9 Structure .........................................................................................9 Documentation Conventions ...........................................................10 Further Reading.............................................................................10

J2EE Guide.........................................................................................12 J2EE Architecture ...............................................................................13

J2EE Components ..........................................................................14 J2EE Containers.............................................................................15 J2EE Clients...................................................................................17 J2EE Services ................................................................................18

J2EE Application Overview ..................................................................19 J2EE Application Components .........................................................19 J2EE Application Structure..............................................................20 Development Roles ........................................................................23 J2EE Applications Development Phases ...........................................24

Enterprise JavaBeans..........................................................................29 Introduction to EJBs.......................................................................29 SAP J2EE Engine Enterprise JavaBeans Architecture.........................31

Web Components...............................................................................34 Overview.......................................................................................34 Web Component Roles ...................................................................34 Web Component Lifecycle ..............................................................35 Servlets.........................................................................................36 JavaServer Pages...........................................................................40

J2EE Examples...................................................................................48 Market Summary................................................................................49

2/309


Market Summary ...........................................................................49 Application Design .........................................................................49 JavaServer Page – YahooFinanceRetriever.jsp .................................51 JavaBean – FacadeBean.java..........................................................53 CM Entity EJBean...........................................................................55 Stateless Session EJBean................................................................55 Core Java Class – YahooFinanceWebContent.java ............................55 Deployment Specifics of MarketSummary Example...........................56

CD Collection .....................................................................................66 Overview.......................................................................................66 Application Components .................................................................66 Application Design and Development ..............................................67

Statistical Calculator ...........................................................................72 Overview.......................................................................................72 Application Components .................................................................72 Application Design and Development ..............................................73

Developers Tasks...............................................................................79 Configuring JBuilder Plug-in for Application Deployment and Debugging 80

Overview.......................................................................................80 Compatibility .................................................................................80 How to Install the Plug-In ..............................................................80 Setting SAP J2EE Engine as Your Default Web Server.......................80 Starting SAP J2EE Engine in JBuilder 5.0 .........................................84 Deploying Applications with JBuilder 5.0..........................................84 Running and Debugging Applications with JBuilder 5.0.....................88

Lookup Resources over the JNDI.........................................................90 Services Lookup.............................................................................90 Binding Local and Global Objects. Persistent and Non-Persistent Statute..........................................................................................91 Lookup from a Different Cluster ......................................................93

3/309


Services Guide ...................................................................................94 Overview ...........................................................................................95 Admin Service ....................................................................................96

Overview.......................................................................................96 Interfaces......................................................................................96 Example ......................................................................................101

Appclient Service..............................................................................103 Overview.....................................................................................103 Interfaces....................................................................................103 Example ......................................................................................107

DBMS Service...................................................................................109 Overview.....................................................................................109 Interfaces....................................................................................110

DBPool Service.................................................................................111 Overview.....................................................................................111 Interfaces....................................................................................111 Example ......................................................................................119

Deploy Service .................................................................................121 Overview.....................................................................................121 Interfaces....................................................................................121 Example ......................................................................................130

EISConnector Service .......................................................................131 Overview.....................................................................................131 Interfaces....................................................................................131 Example ......................................................................................133

EJB1.1 Service .................................................................................134 Overview.....................................................................................134

EJB2.0 Service .................................................................................136 Overview.....................................................................................136 Interfaces....................................................................................136

4/309


Description of inqmy-ejb.xml ........................................................142 File Service ......................................................................................149

Overview.....................................................................................149 Interfaces....................................................................................149 Example ......................................................................................153

HTTP Service ...................................................................................154 Overview.....................................................................................154 Interfaces....................................................................................154 Example ......................................................................................156

HTTP Tunneling Service....................................................................157 Overview.....................................................................................157 Example ......................................................................................157

IIOP Service.....................................................................................158 Overview.....................................................................................158 Interfaces....................................................................................159

JavaMail Service...............................................................................160 Overview.....................................................................................160 Client View ..................................................................................160

JMS Service .....................................................................................161 Overview.....................................................................................161 Developing a JMS Client ...............................................................162 Interfaces....................................................................................164 Example ......................................................................................167

Keystore Service ..............................................................................170 Overview.....................................................................................170 Interfaces....................................................................................170

Log Service ......................................................................................171 Overview.....................................................................................171 Interfaces....................................................................................171

Naming Service ................................................................................176

5/309


Overview.....................................................................................176 Interfaces....................................................................................177

P4 Service........................................................................................178 Overview.....................................................................................178 Interfaces....................................................................................179 Example ......................................................................................181

RFC Engine Service ..........................................................................183 Overview.....................................................................................183 Interfaces....................................................................................183

Security Service ...............................................................................184 Overview.....................................................................................184 Interfaces....................................................................................184 Example ......................................................................................213

Servlets_jsp Service..........................................................................218 Overview.....................................................................................218 Interfaces....................................................................................218 Example ......................................................................................218

Shell Service ....................................................................................219 Overview.....................................................................................219 Interfaces....................................................................................219

SSL Service......................................................................................222 Overview.....................................................................................222 Interfaces....................................................................................223

Telnet Service ..................................................................................224 Overview.....................................................................................224 Interfaces....................................................................................224

Transaction Service (TS)...................................................................225 Overview.....................................................................................225 Interfaces....................................................................................225 Example ......................................................................................230

6/309


Developing Third-Party Visualizations of SAP J2EE Engine Tools...232 Overview .........................................................................................233 Config Tool ......................................................................................234

batchconfig.xml ...........................................................................234 SAP J2EE Engine Installation and Uninstallation Programs ..................239

Manifest.xml................................................................................241 BatchSetup.xml............................................................................245 install_log.xml .............................................................................247 uninstall.xml ................................................................................250

J2EE Tutorials ..................................................................................252 How to Develop a JavaServer™ Page using JBuilder 5 ........................253

Overview.....................................................................................253 Prerequisites................................................................................253 Steps to Create a Simple JSP ........................................................254 Deploy the Example .....................................................................259

How To Develop a Servlet Using JBuilder 5 ........................................264 Introduction ................................................................................264 Prerequisites................................................................................264 Steps to Create a Servlet..............................................................264 Deploy the Example .....................................................................270

How to Develop a Session Enterprise JavaBean™ using JBuilder 5.......278 Overview.....................................................................................278 Prerequisites................................................................................278 Steps to create a Session Enterprise JavaBean...............................278 Deploying the EJBean ..................................................................292

Appendix..........................................................................................303 Message-Driven Bean Deploy Guide ..................................................304

Commands of the Connection Factory ...........................................304 Description of the .EJB file............................................................305 Running the example ...................................................................306

7/309


Running the Connection Factory using SonicMQ as JMS Provider ....307 Sending Messages Between Application and External JMS Server....308 Steps to Run the Example ............................................................308

8/309


About This Manual

This Development Manual describes the basics and the development of J2EE applications, and emphasizes their implementation in real application examples running on SAP J2EE Engine. The manual also contains a detailed description of the structure and functions of SAP J2EE Engine Services and examples of usage. The last chapter of the manual covers the development of third-party visualizations.

Target Audience and Prerequisites

This manual is intended for information technologies programmers responsible for developing, deploying, running and maintaining e-commerce applications using SAP J2EE Engine.

This manual assumes that you are familiar with the following topics:

• The Internet and the World Wide Web • Java programming language

Structure

The contents of this manual is organized into several subsections, as described below:

J2EE Guide

This section covers the basic concepts of the J2EE architecture, and the J2EE application components, structure, and development according to the J2EE Specification™ 1.2, Java Servlet Specification™ 1.1, and Enterprise JavaBeans Specification™ 1.1.

J2EE Examples

This section contains a description of the design concepts, the source code development, the assembling and the deployment specifics of three J2EE application examples.

9/309


Services Guide

This section focuses on the functions and main features of SAP J2EE Engine Services. A simple example is provided for each service that can be accessed directly by the clients.

Developing Third-Party Visualizations of SAP J2EE Engine Tools

This section describes the development of different visualizations for the two SAP J2EE Engine XML-based tools: Config Tool and the Installation and Uninstallation Programs. These can be used if these tools are integrated into more complicated systems, or if third-party visualization is needed.

Documentation Conventions

The following conventions are used in SAP J2EE Engine documentation:

• Italic font Used for file and directory names, system paths, and so on. File and directory paths are in Windows format (with backslashes separating directory names). For Unix versions, the directory paths are the same, except that slashes are used instead of backslashes to separate directories. Example: java.exe, ../cluster/dispatcher/managers/framework.properties, …

• Monospaced font Used for java source code or other specific file contents. Example: Service_0_Name=cluster\dispatcher Service_0_RootDir=C:\SAP_J2EEngine6.20\cluster\dispatcher Service_0_JavaPath=C:\jdk\1.3\bin

Further Reading

For information on SAP J2EE Engine installation, functions and administration, refer to the following SAP J2EE Engine documents:

• Installation Manual • Getting Started • Administration Manual

10/309


• Deployment Manual

11/309


Chapter 1 J2EE Guide

• J2EE Architecture

• J2EE Application Overview

• Enterprise JavaBeans

• Web Components

12/309


J2EE Architecture

J2EE Architecture is a standard for developing Enterprise business systems that effectively replaces all other models.

J2EE is a component-based programming model. This means it consists of many components (perhaps combined in modules) that reside in runtime systems called containers. Along with the standard J2EE services for connection with EIS and communication, they create a stable and secure environment for business applications.

The main concepts in the J2EE architecture are:

• J2EE Components • J2EE Containers • J2EE Clients • J2EE Services

13/309


The J2EE Architecture

J2EE Components

A component is an independent software unit. It can be used independently, or for development of modules used in applications. In addition to the JavaBeans™ component model defined in J2SE, J2EE defines the following components.

Web Components

Web components exist in Web containers that manage client requests using Web browsers. Web containers are situated in the middle tier. J2EE defines two kinds of Web components:

• Servlets • JavaServer Pages™ (JSPs)

14/309


EJB Components

EJB components exist in EJB containers that manage client requests – directly or using Web containers. The EJB containers are situated in the middle tier. The EJB components typically contain the business logic of the application.

• Enterprise JavaBeans™ (EJB)

Application Clients

Applications exist in containers that ensure access to J2EE services and communication. They are executed on their own virtual machine, and are situated in the client tier.

Applets

Java Applets exist in containers that ensure the environment for the applets’ execution. Applets run on their own virtual machine. Typically, Web browsers provide their execution environment.

J2EE Containers

Containers are the interface between a component and the low-level, platform-specific function that supports the component. Before a Web, enterprise bean, or application client component can be executed, it must be assembled into a J2EE application and deployed on its container.

The assembly process involves specifying container settings for each component in the J2EE application, and for the actual J2EE application. The container settings customize the underlying support provided by the J2EE server – include services such as security, transaction management, lookup functions, and remote connectivity. Some of the highlights are:

• The J2EE security model enables you to configure a Web component or enterprise bean so that only authorized users can access the system resources.

• The J2EE transaction model enables you to specify relationships among methods that are executed within a single transaction so that all methods in one transaction are treated as a single unit.

• The J2EE lookup function provides a unified interface to multiple naming and directory services in the enterprise so that application components can access naming and directory services.

15/309


• The J2EE remote connectivity model manages low-level communication between clients and enterprise beans. After an enterprise bean is created, a client invokes methods on it as if it were in the same virtual machine.

Because J2EE architecture provides configurable services, application components within the same J2EE application can behave differently based on where they are deployed. For example, an enterprise bean can have security settings that allow it a certain level of access to database data in one production environment and another level of database access in another production environment.

The container also manages nonconfigurable services such as enterprise bean and servlet life cycles, database connection resource pooling, data persistence, and access to the J2EE platform APIs described in J2EE APIs. Although data persistence is a nonconfigurable service, the J2EE architecture lets you override container-managed persistence by including the appropriate code in your enterprise bean implementation when you want more control than the default container-managed persistence provides. For example, you might use bean-managed persistence to implement your own finder (search) methods or to create a customized database cache.

Container Types

The deployment process installs J2EE application components in the following types of J2EE containers.

• An Enterprise JavaBeans (EJB) container manages the execution of all enterprise beans in one J2EE application. EJBs and their container run on the J2EE server.

• A Web container manages the execution of all JSP and servlet components in one J2EE application. Web components and their container run on the J2EE server.

• An application client container manages the execution of all application client components in one J2EE application. Application clients and their container run on the client machine.

• An applet container consists of the Web browser and its Java plug-in. They both run on the client machine.

16/309


J2EE Server and Containers

J2EE Clients

Web Browser Clients

The user's Web browser downloads static or dynamic Hypertext Markup Language (HTML), Wireless Markup Language (WML), or Extensible Markup Language (XML) Web pages from the Web tier. Dynamic Web pages are generated by servlets, or pages created using the JavaServer Pages technology (JSPs) running in the Web tier.

A Web page downloaded from the Web tier can include an embedded applet. An applet is a small client application written in the Java programming language that executes in the Java Virtual Machine (JVM) installed in the Web browser. However, client systems probably need a Java plug-in and a security policy file so the applet can execute successfully in the Web browser.

JSP pages are the preferred API for creating Web-based client programs because no plug-ins or security policy files are needed on the client systems. Also, JSP pages enable cleaner and more modular application design because they provide a way to separate application programming from Web page design. This means personnel involved in Web page design do not need to understand Java programming language syntax to do their job.

Applets that run in other network-based systems such as hand-held devices or car phones can render Wireless Markup Language (WML) pages generated by

17/309


a JSP page or servlet running on the J2EE server. The WML page is delivered over Wireless Application Protocol (WAP) and the network configuration requires a gateway to translate WAP to HTTP and back again. The gateway translates the WAP request coming from the hand-held device to an HTTP request for the J2EE server, and then translates the HTTP server response and WML page to a WAP server response and WML page for display on the hand-held device.

Application Clients

An application client runs on a client machine and provides a way for users to handle tasks, such as J2EE system or application administration. It typically has a graphical user interface created using Swing or Abstract Window Toolkit (AWT) APIs, but a command-line interface is also possible.

Application clients directly access enterprise beans running in the business tier. However, if the J2EE application needs to open an HTTP connection to establish communication with a servlet running in the Web tier, the application client is able to open such HTTP connection.

J2EE Services

SAP J2EE Engine implements the set of standard J2EE services defined by the Java™ 2 Platform Enterprise Edition Specification, v.1.2:

• HTTP • HTTPS • Java™ Transaction API (JTA) • RMI-IIOP • JavaIDL • JDBC™ • Java™ Message Service (JMS) • Java Naming and Directory Interface™ (JNDI) • JavaMail™

18/309


J2EE Application Overview

J2EE applications consist of components. A J2EE component is a self-contained functional software unit that is assembled into a J2EE application with its related classes and files and communicates with other components. The J2EE Specification™ 1.2 defines the following J2EE components:

• Client components – application clients and applets • Web components – Java Servlet and JavaServer Pages™ (JSP™)

technology components • Business components – Enterprise JavaBeans™ (EJB™) components

(enterprise beans)

These modules are reusable – new applications can be built from existing enterprise beans and components. Because the modules are portable, the application they comprise can run on any J2EE server that conforms to the specifications.

J2EE Application Components

The graphic below shows the hierarchy of a J2EE application. A J2EE application may contain one or more enterprise beans, Web components, or J2EE application client components. An enterprise bean consists of three class files – the EJB class, the remote interface, and the home interface. A Web component may contain files of the following types – servlet class, JSP, HTML, and image files. A J2EE application client is a Java application that runs in an environment (container), which enables it to access J2EE services.

Each J2EE application, Web component, enterprise bean, and J2EE application client has a deployment descriptor. The deployment descriptor is an XML file that describes the component. An EJB deployment descriptor, for example, declares transaction attributes and security authorizations for an enterprise bean. Since this information is declarative, it can be changed without requiring modifications of the bean’s source code. At runtime, the J2EE server reads this information and acts upon the bean accordingly.

19/309


Contents of a J2EE Application

Each module is bundled into a file with a particular format – a J2EE application in an EAR file, an enterprise bean in an EJB JAR file, a Web component in a WAR file, and a J2EE application client in a JAR file. An EAR file, for example, contains an XML file for its deployment descriptor, and one or more EJB JAR and WAR files. An EJB JAR contains its deployment descriptor and the class files of the enterprise bean.

J2EE Application Structure

J2EE applications consist of components that are separated into three modules:

• Web Module • EJB Module • J2EE Application Client Module

These modules are encapsulated in an individual unit – EAR (Enterprise ARchive) file. The EAR files are used as a standard format for enterprise applications.

20/309


Enterprise applications, as well as the modules and their components, have a deployment descriptor – an XML file in a corresponding archive file (EAR, JAR, WAR).

Web Components

The Web components are packed in Web Archive (WAR) files with a war extension. They possess a deployment descriptor – an XML file used for setting up the component properties.

The Web components contain:

• Servlet Java Class files, and the classes they depend on (which can be packed in a separate JAR file)

• JavaServer Pages (JSPs) and their helper Java classes • Static Web files and Web documents (HTML, images, sound files, and

so on) • Java applets and their classes • Web Deployment Descriptor

Web Components

Enterprise JavaBean™ Components

EJB components are packed in JAR files that have a jar extension. The JAR files have a deployment descriptor – an XML file used for setting up the component properties.

The EJB components contain:

21/309


• Enterprise Beans’ Java Class files • The Java Class files the Enterprise Beans depend on. These classes do

not exist in the J2EE platform – they are defined separately • EJB Deployment Descriptor, which provides information about the

composition and structure of the application

EJB Components

J2EE Application Client Module

J2EE Application Clients exist in an environment where they can communicate with the J2EE platform. J2EE Application Clients are distributed as JAR files containing the Java Client application with all necessary classes and a Deployment Descriptor.

22/309


J2EE Application Client Module

Development Roles

Reusable modules enable you to divide the application development and deployment process into distinct roles so different people or companies can perform different parts of the process.

The first two roles involve purchasing and installing the J2EE product and tools. Once the software is purchased and installed, J2EE components can be developed by application component providers, assembled by application assemblers, and deployed by application deployers. In a large organization, different individuals or teams can execute each of these roles. This division of labor works because each of the earlier roles outputs a portable file that is the input for a subsequent role. For example, in the application component development phase, an enterprise bean software developer delivers EJB JAR files. In the application assembly role, another developer combines these EJB JAR files into a J2EE application and saves it in an EAR file. In the application deployment role, a system administrator at the customer site uses the EAR file to install the J2EE application on a J2EE server.

The most clearly defined roles are:

• Component Provider • Application Assembler • Application Deployer

23/309


J2EE Applications Development Phases

As a J2EE application evolves, it passes through the following development phases:

• Creating Enterprise JavaBean • Creating Web Component • Creating J2EE Application Client • J2EE Application Assembling • J2EE Application Deployment

24/309


J2EE Application Assembly and Deployment

The following sections summarize the development phases of J2EE applications. Since a J2EE application is not required to have every type of module, only one of the first three phases is required. The two final phases are necessary.

Creating Enterprise Bean

Person: software developer

Tasks:

25/309


• Codes and compiles the Java source code needed by the enterprise bean

• Specifies the deployment descriptor for the enterprise bean • Bundles the class files and the deployment descriptor into an EJB JAR

file

Deliverable: the EJB JAR file containing the enterprise bean

Enterprise Bean Creation

Creating Web Component

Persons: Web designer (JavaServer Pages components), software developer (Servlets)

Tasks:

• Code and compile Java source code for the servlet • Write JSP and HTML files • Specify the deployment descriptor for the Web component • Bundle the Class, JSP, HTML, and deployment descriptor files into the

WAR file

Deliverable: the WAR file containing the Web component

26/309


Web Component Creation

Creating J2EE Application Client


Tasks:

• Codes and compiles the Java source code needed by the client • Specifies the deployment descriptor for the client • Bundles the .class files and deployment descriptor into the .jar file for

the client

Deliverable: the .jar file containing the J2EE application client

J2EE Application Client Creation

J2EE Application Assembling


Tasks:

• Assembles enterprise beans (in EJB JARs) and Web components (in WARs) created in the previous phases into a J2EE application archive (EAR)

• Specifies the deployment descriptor for the J2EE application

27/309


Deliverable: the EAR file containing the J2EE application

J2EE Application Assembly

J2EE Application Deployment

Person: system administrator

Tasks:

• Configures the J2EE application for the operational environment by modifying the deployment descriptor of the J2EE application

• Deploys (installs) the J2EE application (EAR) on the J2EE server

Deliverable: an installed and configured J2EE application

28/309


Enterprise JavaBeans

Introduction to EJBs

SAP J2EE Engine implements Enterprise JavaBeans™ (EJB™) architecture – part of the Java™ 2 Platform, Enterprise Edition – which is a component architecture for creating scalable, multitier, distributed applications.

Description and Functions

Enterprise JavaBeans is a technology for developing, assembling, deploying, and managing distributed applications in an enterprise environment. It simplifies the handling of issues inherent in distributed applications. By concealing such complexities as security, transaction handling, and database access, the EJB architecture enables component developers to focus on business logic.

Enterprise JavaBeans applications are platform independent. Once developed, EJBs can be deployed on multiple platforms without recompilation or source code modification.

The Enterprise JavaBeans architecture is compatible with, and uses, other Java programming language APIs. EJBs can interoperate with non-Java programming language applications and are compatible with the CORBA protocols.

Types of EJBs

There are two types of enterprise beans – session beans and entity beans – representing different types of business logic abstractions.

Session beans represent behavior associated with client sessions. Typically, they are implemented to perform a sequence of tasks within the context of a transaction. A session bean is a logical extension of the client program, running processes on the client’s behalf remotely on the server.

Entity beans represent specific data or collections of data, such as a row in a relational database. Entity bean methods provide operations that act on the data represented by the bean. The data that an entity bean represents is persistent; therefore entity beans survive as long as their data remains in the

29/309


database – that is, they survive server crashes. Entity beans can have bean-managed or container-managed persistence.

Enterprise JavaBeans Versus JavaBeans

JavaBeans and EJBs, have some basic similarities. They are objects or components created with a set of characteristics to do their own specific job, and they have the ability to take on other characteristics from the container on the server in which they reside. This enables a bean to behave differently depending on the specific job and environment where it is placed.

The beans are components that have interfaces in them or properties associated with them so they can be interrogated by and integrated with other beans that were developed by different people at different times. A bean can be built and tied together with other beans later at construction time. This provides a way to build something and use it again later; that is the notion of a component. This means the beans are platform independent. Once a bean is written, it can be used on any platform that supports Java.

The difference from pure objects is that it has an external interface, called the properties interface, which enables a tool to read what the component is supposed to do, and hook it up to other beans and plug it into another environment. That is true of JavaBeans and EJBs.

Despite the similarities, EJBs have several critical advantages over JavaBeans. JavaBeans are developed to act and run in a certain way. They can be on the client or on the server. Because the JavaBean components are simple and have limited functions, the beans may not cover all the actions needed by the enterprise. It would take a programmer a lot of development time to write new code for the extra functions a bean might require, such as accessibility, lifecycle management, transaction management, and security. EJBs provide the needed functions, thereby moving the business and data manipulation logic to the second-tier server. In this way, the applications take advantage of the power of high-end, multithreaded, and multiprocessing systems as server components, such as EJBs, to pool and share scarce resources.

JavaBeans are intended to be local to a single process, and they are often visible at runtime. An EJB is a nonvisual, remote object designed to run on a server and be invoked by clients. EJBs are intended to live on one machine and be invoked remotely from another machine. They have a deployment descriptor that is intended for the same purpose as JavaBean properties. It is a description about the bean that can be read later by a tool.

30/309


EJBs are remotely executable components or business objects deployed on the server. Their protocol enables them to be accessed remotely and to be installed or deployed on a particular server. They have a set of mechanisms that enables them to delegate major qualities of service, security, transactional behavior, concurrency (the ability to be accessed by more than one client at a time), and persistence (how their state can be saved) to the container in which they are placed on the EJB server. They get their behavior from being installed in a container.

JavaBeans are governed by JavaBeans Component Specification™, and EJBs have to meet the requirements of Enterprise JavaBeans Specification™.

EJB1.1 and EJB2.0

SAP J2EE Engine fully supports Enterprise JavaBeans™ Specification, v1.1 from Sun™ Microsystems and partly implements the features of Enterprise JavaBeans™ Specification, v2.0. The EJB 2.0 implementation is expected to change in future releases of SAP J2EE Engine.

SAP J2EE Engine Enterprise JavaBeans Architecture

SAP J2EE Engine implements EJB1.1 and EJB2.0 containers, which support the following services: JMS, JNDI, RMI-IIOP, JTA, JavaMail, JDBC.

31/309


Enterprise JavaBeans Architecture

The SAP J2EE Engine EJB architecture contains the following components:

• SAP J2EE Engine EJB container o Provides environment for EJB existence o Creates and manages the EJB instances at runtime o Enables multiple EJBs to be deployed on SAP J2EE Engine EJB

container o Manages the client access to EJBs deployed on the SAP J2EE

Engine EJB container. Grants permission to the client methods to invoke the EJB business methods.

o Manages the transactions, security, and exceptions on behalf of the enterprise bean instances

o Provides the deployed EJBs with network distribution of clients and scalable management of resources

o Generates the EJBObjects and the Home Objects classes • EJBObjects – the clients use the EJBObjects to access the EJB business

methods. SAP J2EE Engine EJB container generates the EJBObjects classes.

• EJBHome Objects – the client accesses the EJBHome Object using the JNDI (Java Naming and Directory Interface) API extension. EJBObjects are created using the EJBHome create() method, found by the EJBHome find() method, and removed by the EJBHome remove() method.

32/309


Structure

A typical EJB consists of an EJB class file, two interfaces, and a deployment descriptor. It may also contain several helper classes.

Remote Interface

The bean’s Remote interface contains the methods in which the client may be interested. The client is not allowed to obtain a direct reference to the EJBObject. The Remote interface is used by SAP J2EE Engine EJB container to generate the client’s stub and a server-side proxy object that passes the client’s calls to the EJBObject. The EJB Remote interface inherits the javax.ejbEJBObject interface.

Home Interface

The bean’s Home interface is the bean component, which the client looks up. The Home interface extends the javax.ejb.EJBHome interface. The client obtains a reference to the Home interface using JNDI, then calls its create() method to get a reference to an object that implements the Remote interface. The implementation of the Home interface is handled by SAP J2EE Engine EJB container.

Enterprise Bean Class

The bean class inherits the corresponding bean interface (session beans inherit javax.ejb.SessionBean interface, entity beans inherit javax.ejb.EntityBean interface) and implements the business methods declared in the Remote interface. The bean class should implement the create() methods declared in the EJB’s Home interface in its ejbCreate() methods. The ejbCreate() methods should have the same signature as the corresponding create() methods. When the container generates an implementation of the Home interface, it calls the bean’s ejbCreate() method for each corresponding create() method in the Home interface.

Deployment Descriptor

This describes the EJB and its elements in an XML file.

33/309


Web Components

Overview

When Web-based clients of J2EE applications communicate with the SAP J2EE Engine, they use server-side objects called Web components. There are two types of Web components:

• Java™ Servlets – Servlets are Java programming language classes that process requests and construct responses dynamically

• JavaServer Pages™ (JSP™) – JSP pages are text-based documents that execute as Servlets, but allow a more natural approach to creating static content

SAP J2EE Engine fully supports Java™ Servlets Specification v2.2 and JavaServer Pages™ Specification v1.1, and is in a process of implementation of Java™ Servlets Specification v2.3 and JavaServer Pages™ Specification v1.3.

Most Web-based J2EE clients use the HTTP protocol to communicate with a J2EE server. SAP J2EE Engine has ensured full compatibility with the HTTP/1.1 protocol because HTTP is a major aspect of Web components. HTTP defines the requests that a client can send to a server, and the responses the server can send in reply. Each request contains a URL, which is a string that identifies a Web component, or a static object, such as an HTML page or an image file.

Web Component Roles

Web applications provide dynamic and interactive content to browser-based clients. Browser-based Web applications can be used for any type of application – from secure business-to-business applications to electronic commerce Web sites. Although a common view is that Web components are used mainly to provide an application’s presentation, in the J2EE application programming model Web components can serve two roles – as presentation components and as front components.

Presentation components generate the HTML/XML response that, when rendered, determines the user interface. A JSP page acting as a presentation component may contain reusable custom tags or presentation logic. A

34/309


presentation component could also be a servlet that produces binary data, such as an image.

Front components do not do any presentation, but manage other components and handle HTTP requests, or convert the requests into a form that an application can understand. Front components are useful because they provide a single entry point to an application, thus making security, application state, and presentation uniform and easier to maintain.

The front component accepts a request, and then determines the appropriate presentation component to forward it to. The presentation component then processes the request and returns the response to the front component, which forwards it to the server for presentation to the user.

Web Component Roles

Web Component Lifecycle

Depending on the J2EE platform, SAP J2EE Engine provides many supporting services that enhance the capabilities of Web components and make them easier to develop. Web components run within the SAP J2EE Engine Web container. The Web container provides services such as request dispatching, security, concurrency, and life cycle management. It also gives Web

35/309


components access to the J2EE platform APIs such as naming, transactions, and e-mail. Before it can be executed, a Web component must be installed (or deployed) into a Web container.

Certain aspects of Web component behavior can be configured when it is packaged and deployed. The configuration information is maintained in a text file in XML format called a Web application deployment descriptor. When you package and deploy Web components using the SAP J2EE Engine Deploy Tool, it generates or updates the deployment descriptor based on data that you enter in Deploy Tool wizards and inspectors.

The process of creating, deploying, and executing a Web component can be summarized as follows:

• Developing the Web component code (perhaps with a deployment descriptor)

• Packaging the Web component along with any static resources (for example – images) referenced by the component

• Deploying the application • Accessing an URL that references the Web component

Servlets

Introduction

Java Servlets are small, platform-independent Java programs that can be used to extend the server functions. Servlets are compiled of byte code that can be loaded dynamically and that extend the capabilities of the host. Servlets differ from applets in that servlets do not run in a Web browser or with a graphical user interface. Instead, servlets interact with the servlet engine running on the Web server using requests and responses. The request-response paradigm is modelled on the behavior of the Hypertext Transfer Protocol (HTTP). A client program, which could be a Web browser or some other program that can make connections across the Internet, accesses a Web server and makes a request. This request is processed by the servlet engine that runs with the Web server, which returns a response to a servlet. The servlet in turn sends a response in HTTP form to the client. Servlets are an effective replacement for Common Gateway Interface (CGI) scripts. They provide a way to generate dynamic documents that is both easier to write and faster to run. Unlike CGI, programs servlets must not be specific to either a platform or a server.

36/309


Servlets have the following advantages over other common server extension technologies:

• They are faster than Common Gateway Interface (CGI) scripts because they use a different process model.

• They use a standard API that is supported by many Web servers. • They have all of the advantages of the Java language, including ease

of development and platform independence. • They can access the large set of APIs available for the Java platform.

Servlet Architecture

The central abstraction in the JSDK is the Servlet interface. All servlets implement this interface by extending a class that implements it, such as HttpServlet. The Servlet interface provides methods that manage the servlet and its communication with clients.

Servlet writers provide some or all of these methods when developing a servlet. When a servlet accepts a call from a client, it receives two objects – the ServletRequest and the ServletResponse.

The ServletRequest class encapsulates the communication from the client to the server, while the ServletResponse class encapsulates the communication from the servlet back to the client. The ServletRequest interface enables the servlet to access information, such as the names of the parameters passed in by the client, the protocol (scheme) being used by the client, and the names of the remote host that made the request and the server that received it. It also provides the servlet with access to the input stream, ServletInputStream, through which the servlet gets data from clients that are using application protocols, such as the HTTP POST and PUT methods. Subclasses of ServletRequest enable the servlet to retrieve more protocol-specific data.

The ServletResponse interface gives the servlet methods for replying to the client. It enables the servlet to set the content length and MIME type of the reply, and provides an output stream, ServletOutputStream, and a Writer through which the servlet can send the reply data. Subclasses of ServletResponse give the servlet more protocol-specific capabilities.

Servlet Lifecycle

The lifecycle of a Java servlet defines how the servlet is loaded and initialized, how it receives and responds to requests, and how it is taken out of service. The servlet lifecycle is defined by the javax.servlet.Servlet interface. All

37/309


Java servlets must, either directly or indirectly, implement the javax.servlet.Servlet interface so that they can run in a servlet engine. The servlet engine provides network services, understands MIME requests, and runs servlet containers.

When a service loads a servlet, it runs the servlet’s init method. Even though most servlets are run in multithreaded services, there are no concurrency issues during servlet initialization. This is because the service calls the init method once, when it loads the servlet, and does not call it again unless it is reloading the servlet. The service cannot reload a servlet until it has removed the servlet by calling the destroy method.

Initialization is allowed to complete before client requests are handled (that is, before the service method is called) or the servlet is destroyed. After the service loads and initializes the servlet, the servlet is able to handle client requests. It processes them in its service method. Each client’s request has its call to the service method run in its own servlet thread: the method receives the client’s request, and sends the client its response.

Servlet Lifecycle

Servlets run until they are removed from the service – for example, at the request of a system administrator. When a service removes a servlet, it runs the servlet’s destroy method. The method is run once; the service cannot run it again until after it reloads and reinitializes the servlet. When the destroy method runs, however, other threads might be running service requests. If, in cleaning up, it is necessary to access shared resources (such as network connections to be closed), that access should be synchronized. During a servlet’s lifecycle, it is important to write thread-safe code for destroying the servlet and, unless the servlet implements the SingleThreadModel interface, servicing client requests.

38/309


Loading and Instantiating

The servlet engine instantiates and loads a servlet. The instantiation and loading can occur when the engine starts, when it needs the servlet to respond to a request, or any time in between. The servlet engine loads a servlet using the Java class loading facility. The servlet engine can load the servlet from the local file system, a remote file system, or a network source.

Initializing a Servlet

After the servlet engine loads the servlet, the engine must initialize it. Initialization is a good time for a servlet to read any persistent data it may have stored, initialize JDBC database connections, and establish references to other costly resources. During initialization, the init method of the javax.servlet.Servlet interface gives the servlet initialization information, so that the servlet has an opportunity to configure itself. The init method takes a servlet configuration object (of type ServletConfig) as a parameter. The servlet configuration object is implemented in the servlet engine and enables the servlet to access name-value parameters from the engine’s configuration information. The servlet configuration object also gives the servlet access to a servlet context object, of type ServletContext.

Handling Requests

After the servlet is initialized, it is ready to handle client requests. Each request is represented by a servlet request object (of type ServletRequest). The servlet response is represented by a servlet response object (of type ServletResponse). When the client makes a request, the servlet engine passes both the servlet request object and the servlet response object to the servlet. The objects are passed as parameters to the service method, defined in the Service interface, which the servlet implements. The servlet can also implement the ServletRequest or ServletResponse interfaces, or both.

The ServletRequest interface gives the servlet access to the request parameters the client sends, such as form data, request information, and protocol methods. The servlet can read the request data from an input stream object (of type ServletInputStream).

The ServletResponse interface enables the servlet to set response headers and status codes. By implementing ServletResponse, the servlet has access to an output stream object (of type ServletOutputStream) that it can use to return data to the client.

39/309


Multithreading and Mapping

In a multithreaded environment, most servlets must be written to handle multiple concurrent requests. The exception is a servlet that implements the SingleThreadModel interface. Such a servlet can execute only one request thread at a time. A servlet responds to a client request according to the servlet engine’s mapping. A mapping pairs a servlet instance with a URL to which the servlet returns data. However, a mapping might pair a URL with more than one servlet instance. For example, a distributed servlet engine running on more than one server might have a servlet instance running on each server, to balance the processing load.

Destroying a Servlet

The servlet engine is not required to keep a servlet loaded for any period of time, or for the life of the server. Servlet engines are free to use servlets or retire them at any time. When the servlet engine determines that a servlet should be destroyed, the engine must allow the servlet to release any resources it is using and save persistent state. To do this, the engine calls the servlet’s destroy method. The servlet engine must allow any calls to the service method either to complete or to end with a time out (as the engine defines a time out) before the engine can destroy the servlet. Once the engine destroys a servlet, the engine cannot route any more requests to the servlet. The engine must release the servlet and make it eligible for garbage collection.

JavaServer Pages

Introduction

JavaServer Pages™ (JSP™) technology enables easy creation of Web content that has both static and dynamic components. The JSP technology projects all the dynamic capabilities of Java Servlet technology, but provides a more natural approach to creating static content.

JSP technology uses the Java™ programming language as its default scripting language. This way, scripting on the server side can take full advantage of the powerful set of capabilities that the Java programming language offers. In addition, the JSP technology provides a way to easily access reusable components such as JavaBeans™.

Until recently, the typical way to generate dynamic HTML content was:

40/309


• Calling a CGI script • Using a server-side scripting language in the HTML page

Both of these approaches have the same disadvantages: they mix content generation with presentation logic. The Web page designer and the servlet (or business logic) developer are different people possessing different skill sets. JavaServer Pages technology offers solutions that help both Web page developers and business logic developers do their own jobs without having to worry about the other.

JSP Access Model

The server can use JSP in two ways:

• A request comes to a JSP file. The page accesses reusable components, such as JavaBeans, that perform particular well-defined computations (such as accessing a database) and store result sets as bean properties. The page uses components to generate dynamic content and sends it back to the client.

• A request comes to a servlet, which generates some dynamic content and invokes a JSP file to present this content.

There are two APIs that support this model of request processing using JavaServer Pages technology. The first one facilitates passing context between the invoking servlet and the JavaServer Pages file. The other API lets the invoking servlet specify the JavaServer Pages file to use.

A Request Comes to a JSP File

In the JavaServer Pages request model shown below, the client makes a request that is handled by a JavaServer Pages file. The JavaServer Pages file passes the request parameters to a bean component. The JSP file can then query the bean to obtain the results of the computation.

41/309


JSP Request Model

Some example bean components that can be used within a JavaServer Pages file are a JDBC or EJBs. The JSP file, using standard bean property readers, obtains results. The results are displayed in a browser. Typically, the bean developer is a Java programmer and the JavaServer Pages designer is a Web page designer or an HTML programmer. JavaServer Pages technology enables them to do their job by separating content generation from presentation logic.

A Request Comes to a Servlet

Another way to achieve the same effect is shown in the JavaServer Pages request model below. The client makes a request that is handled by a Java servlet. The servlet then generates the content to be displayed in the HTML page. In this example, the servlet uses JDBC to communicate with a database to obtain the content. The resulting content is wrapped into a bean, which is passed to a JavaServer Pages file. The JSP uses the content generated by the servlet and presents it in HTML.

In this case, content generation is handled by the servlet and the JavaServer Pages file handles content presentation.

42/309


JSP Request Model

Syntax

The JavaServer Pages syntax can be divided into three main areas.

JSP Directives

Directives provide global information that is conceptually valid independent of any specific request received by the JSP page. For example, a directive can be used to indicate the scripting language to use in a JSP page.

Declarative statements include syntax, which specifies the:

• Scripting language being used • Interfaces a servlet implements • Class a servlet extends • Packages a servlet imports

The syntax is extensible.

JSP Scriptlets

A JSP scriptlet is used to contain any code fragment that is valid for the scripting language used in a page. The syntax for a scriptlet is:

<% scripting language statements %>

43/309


JSP Expressions

This syntax defines an expression to be evaluated. The expression value is substituted when the expression occurs.

The following section provides a detailed description of the syntax items.

JavaServer Pages Directives

The general syntax of the JavaServer Pages directive is

<%@ (variable="value")+ %>

The possible variables are:

import

The import variable defines the list of packages to be imported by the servlet. This is a comma-separated list of Java language package names or class names that the servlet imports. This tag can be used numerous times within a file to import different packages. An example is:

<%@ import="java.io.*,java.util.Hashtable" %>

content_type

The content_type variable defines the content type of the generated response. By default, a text/html content type is generated. However, the default can be overridden by setting this directive. When used more than once, only the first tag is significant. An example is:

<%@ content_type="text/html;charset=UTF-8" %>

implements

The implements variable defines the list of interfaces that the generated servlets implement. The value for this variable is a comma-separated list of Java language interface names. This tag can be used several times within a file to implement different interfaces.

extends

The extends variable defines the super class of the generated servlet. The value is the name of the Java language class from which the servlet extends.

44/309


The scope of this tag spans the entire file. When used more than once, only the first tag is significant. An example is:

<%@ extends="javax.servlet.http.HttpServlet" %>

JavaServer Pages Scriptlets

The body of the JavaServer Pages scriptlet is the most significant part of the generated servlet service method unless a specific method directive is specified. Any valid Java code can be used. The script specified here can rely upon a set of predefined variables. These variables are:

• request – the servlet request class as defined by javax.servlet.http.HttpServletRequest

• response – the servlet response class as defined by javax.servlet.http.HttpServletResponse

• out – the servlet output writer class as defined by java.io.PrintWriter

• in – the servlet input reader class as defined by java.io.BufferedReader

The actual code is embedded between <% and %> tags. For example:

<% out.println("Hello"); %>

Or

<% foo = request.getParameter("Name"); out.println(foo); %>

JavaServer Pages Expressions

These are tags that contain Java language expressions and that will be replaced with the values of those expressions. They are specified between <%= and %> tags. Expressions specified within these tags are evaluated. The result is converted into a string and displayed. Conversions to string representation for all primitive types such as int, float, and so on, are provided automatically. For example, the following substitutes the value of foobar in place of the tag:

<%= foobar %>

45/309


JSP APIs

There are two JavaServer Pages APIs:

• com.inqmy.services.servlets_jsp.server.HttpServletRequestFacade

This class implements the javax.servlet.http.HttpServletRequest interface and adds a method to set attributes defined by name.

• com.inqmy.services.servlets_jsp.server.HttpServletResponseFacade

This class implements the javax.servlet.http.HttpServletResponse interface and adds a method that enables Servlets to call pages and optionally pass a context.

Application Model

JSP pages can be used in combination with Servlets, HTTP, HTML, XML, Applets, JavaBeans components and EJB components to implement a broad variety of application architecture(s) or models.

Simple 2 1/2 -Tier Application

The simple two-tier model enables a JSP (or a Servlet) to access some external resources directly (such as a database or legacy application) to service a client’s request. The advantage of such a scheme is that it is simple to program, and enables the page author to generate dynamic content based upon the request and state of the resource(s). However, this architecture does not scale for a large number of simultaneous clients because each must establish or share (ad hoc) a (potentially scarce or expensive) connection to the resource(s) in question.

Two-tier Model

N-tier Application

In this model, the application is composed of (n>=3) tiers, where the middle tier, the JSP, interacts with the backend resources using an EJB component. The EJB and the EJB server provide managed access to resources, thereby addressing the performance issues. An EJB server can also support transactions and access to underlying security mechanisms to simplify

46/309


programming. This is the programming model supported by the Java 2 Platform Enterprise Edition (J2EE).

N-tier Model

47/309


Chapter 2 J2EE Examples

• Market Summary Example

• CD Collection Example

• Statistical Calculator Example

48/309


Market Summary

Market Summary

This application retrieves market summary data, such as “DOW Volume” or “NASDAQ Index-Level” from either the Web site http://finance.yahoo.com or a database. The application is written in Java Programming Language and is compliant with Java SDK SE 1.3.0 and EE 1.1.

Application Design

The following graphic illustrates the applications structure:

/MarketSummaryWAR/YahooFinance

FacadeBean.class

DB: STKDATATable: marketsummary

http://f inance.yahoo.com :Nasdaq & NYSE VolumesDow , Nasdaq, 30Year Bond & S&P 500 Index

YahooFinanceWebContent.class

EJB-Env ironment( proxy Host, proxy Port )

CM Entity Bean:MarketSummary Bean.class

MarketSummary Home.class MarketSummary .class YahooFinanceHome.class YahooFinance.classStateless SessionBean:

YahooFinanceBean.class

The application consists of the following parts:

• A JavaServer Page (YahooFinanceRetriever.jsp) that displays the data in a browser and provides for the connection between the client and the application

49/309


• A JavaBean (FacadeBean.java) that contains the main functions of the application, thereby making any further development and changing easier

• The elements that contain the business logic of the application. This part is separated functionally in two subparts: o The first establishes a connection with the database. This

connection is established using a container-managed Entity Enterprise JavaBean.

o The second retrieves the data from the Internet. This subpart consists of a Stateless Session EJB and a java file (YahooFinanceWebContent.java).

Application Components Name Description Design Aspects

YahooFinanceRetriever.jsp

A JSP file that generates the frontends’ look and feel by means of data it receives from a dispatching JavaBean.

A view-related component. It can be upgraded easily without influencing the application logic.

FacadeBean.java A JavaBean file that acts as an intermediary or dispatcher between the frontend component (JSP) and the components implementing the application logic.

A controller-related component. It can be upgraded easily without influencing the application logic. This is a rudimentary implementation of the Facade Pattern.

MarketSummaryBean.java MarketSummaryHome.java MarketSummary.java MarketSummaryPK.java

A container-managed Entity EJB responsible for interactions (Insert/Update/Select) with the Database.

A model-related component. It can be upgraded easily without influencing other components.

YahooFinanceBean.java YahooFinanceHome.java YahooFinance.java

A Stateless Session EJB that sets up a connection with the Internet site http://finance.yahoo.com and retrieves market summary data.

A model-related component. It can be upgraded easily without influencing other components.

50/309


YahooFinanceWebContent.java

A core Java program that takes proxy data to connect to the Internet site http://finance.yahoo.com and to retrieve market summary data.

A utility file that can be used in any appropriate context.

The structure of this application is designed to provide easier modification and redevelopment of the source code to meet specific client requirements. The designer can change the visual design of the application (that is, the .jsp file) without the need of special knowledge of Java programming language. The developer can manage the business logic of the application easily, as the application is divided into separate modules. The source code is not further complicated by additional methods. The additional methods are located in separate files.

JavaServer Page – YahooFinanceRetriever.jsp

This JSP file generates the frontends’ look and feel by means of data it receives from a dispatching JavaBean. There are some HTML-specific content files (*.jpg, *.gif, *.css) embedded in the JSP file.

The initial call to the JSP translates it to a corresponding servlet, compiles the servlet and then loads the servlet file into the application server memory. The <jsp:useBean> tag in the original JSP file causes the loading and instantiation of the FacadeBean during the load process of the JSP’s servlet file:

<jsp:useBean id="myFacadeBean" class="j2ee.marketsummary.FacadeBean" scope="session" />

This action associates an instance of the FacadeBean defined within a given scope available with a given id using a newly declared scripting variable of the same id. The class element must contain the fully qualified name of the class that defines the implementation of the object. The class name is case sensitive. The scope, within which the reference is available, is specified in the scope element.

When an instance of the FacadeBean is created, a <jsp:setProperty> tag must be specified. It ensures access to all FacadeBean set methods:

<jsp:setProperty name="myFacadeBean" property="*"/>

The jsp:setProperty action sets the value of the properties in the FacadeBean. The name element must contain the name of the Bean instance

51/309


defined by the <jsp:useBean> element – that is, myFacadeBean. The Bean instance must contain the property to be set. The defining element must appear before the <jsp:setProperty> element in the same file. The property element contains the name of the Bean property whose value you want to set. In this example, this element is set to “*”, which means that the tag iterates over the current ServletRequest parameters, matching parameter names and value type(s) to property names and set method type(s), setting each matched property to the value of the matching parameter.

The JSP file searches the FacadeBean Hashtable for stored data for a specified day. If such data exists in the FacadeBean, it is visualised by the JSP file. This source code reads all properties from the getMarketSummaryData() method in the FacadeBean:

<% myMarketSummaryData = myFacadeBean.getMarketSummaryData(); if ( myMarketSummaryData != null && !myMarketSummaryData.isEmpty() ) { toDay.set(toDay.DAY_OF_YEAR, myFacadeBean.getDayOfYearSelected()); %>

The variable values are taken from the myMarketSummaryData Hashtable and are visualized in the JSP file:

<% myMarketSummaryDataKeys = myMarketSummaryData.keys(); while ( myMarketSummaryDataKeys.hasMoreElements() ) { nextKey = (String)myMarketSummaryDataKeys.nextElement(); %>

When the data is displayed, a “Store the Market Summary in the Database” option appears. This enables you to store the data in a database:

<INPUT TYPE="SUBMIT" NAME="storeMarketSummaryProperty" VALUE="Store the Market Summary in the Database">

This action submits the form. The JSP file is loaded again with the loaded client data. The getStoreMarketSummaryProperty() method in the FacadeBean is then activated. This method stores the data, received for the current day, in a database of a RDBMS, which must be provided for this application.

The market summary data is retrieved from the Internet site http://finance.yahoo.com only if the user has chosen the current date. In any other case, the data is retrieved from the database if there is data corresponding to the chosen date stored in the database on previous dates.

52/309


JavaBean – FacadeBean.java

The controller component in the application – FacadeBean.java – is a JavaBean. It performs the search (JNDI lookup) and instantiation (using the home objects) of the EJB components. This JavaBean also delegates the invocation (using the remote object) of client requests to the corresponding EJB components. The FacadeBean file acts as an intermediary or dispatcher between the frontend component (JSP) and the components implementing the application logic.

The following method allocates the client requests and determines whether to search in the database or to retrieve data from http://finance.yahoo.com:

public void setMarketSummaryProperty(String myMarketSummaryProperty)

In the first part of this method, the date and time are defined using myCalendar = java.util.Calendar.getInstance() – this returns a GregorianCalendar object whose time fields have been initialized with the current date and time.

A try-catch block is then executed. If the current date is chosen, the YahooFinanceHome.java is started and its getMarketSummary() method is executed. If the chosen date is not the current date, the database is searched for existing data for the corresponding date. If such data exists, it is read and written in a Hashtable. The data from the Hashtable is visualised by the JSP file. If no data is found for the corresponding date, an empty table is returned.

If the Session EJB is started, the following methods are executed in the FacadeBean:

Method Description

private YahooFinance getYahooFinance()

Calls the Home Interface create() method that returns the Bean’s instance.

Private YahooFinanceHome getYahooFinanceHome(String objectName)

Lookups the Home Interface. For this purpose, the static Object getMyInitialContextObject(String objectName) method in the FacadeBean is used.

private void createYahooFinance(YahooFinanceHome home)

Calls the YahooFinanceHome.java create() method.

53/309


When the Entity EJB is started, the following methods are executed in FacadeBean:

Method Description

public MarketSummary setNewMarketSummary(Hashtable myHashtable)

Calls the Home Interface create() method that returns the Bean’s instance.

private MarketSummaryHome getMarketSummaryHome(String objectName)

Lookups the Home Interface. For this purpose, the static Object getMyInitialContextObject(String objectName) method in the FacadeBean is used.

private void createMarketSummary(MarketSummaryHome home, Hashtable myHashtable )

Calls the MarketSummaryHome.java create() method.

When there is a client request to store data in the database, the following methods are executed in FacadeBean:

Method Description

public void setStoreMarketSummaryProperty(String myStoreMarketSummaryProperty)

Checks the FacadeBean Hashtable for data. If this Hashtable contains data, the data is stored in the database.

private void createMarketSummary(MarketSummaryHome home, Hashtable myHashtable )

Stores a new data query in the database.

Note: When the FacadeBean stores data in the database, it looks up the MarketSummaryHome.java again.

54/309


CM Entity EJBean

The container-managed Entity EJBean interacts (Insert, Update, Select) with the Database. It interacts with the database using a data source, which must be provided before deployment. The SAP J2EE Engine Visual Administrator manages the data source set up. This data source provides the container-managed Entity EJBean with pre-allocated database connections in a connection pool.

Stateless Session EJBean

The Stateless Session EJBean sets up a connection with the Internet site http://finance.yahoo.com and retrieves market summary data, such as S&P 500 or NASDAQ Volume data. This data can be stored in and retrieved from the database depending on the selected date on the JSP page. The session bean uses the YahooFinanceWebContent.java to open a URL connection to Internet. The YahooFinanceWebContent.java needs proxy data to work correctly. This data is provided as session beans environment data-value pairs.

In the YahooFinanceBean.java, an instance of YahooFinanceWebContent.java is created. A proxy is specified and a port is opened. The YahooFinanceWebContent.java getMarketSummary() method is returned.

public Hashtable getMarketSummary() { YahooFinanceWebContent myYahooFinanceWebContent = new YahooFinanceWebContent(); try { String proxyHost = (String)FacadeBean.getMyInitialContextObject("java:comp/env/proxyHost"); String proxyPort = (String)FacadeBean.getMyInitialContextObject("java:comp/env/proxyPort"); return myYahooFinanceWebContent.getMarketSummary(proxyHost, proxyPort); } catch ( Exception e ) { return myYahooFinanceWebContent.getMarketSummary(); }

Core Java Class – YahooFinanceWebContent.java

This Core Java class takes proxy data to connect to the Internet site http://finance.yahoo.com and to retrieve market summary data.

55/309


The following two methods are used to perform this:

• public Hashtable getMarketSummary(String proxyHost, String proxyPort)

• public Hashtable getMarketSummary()

Deployment Specifics of MarketSummary Example

Note: This section describes only some of the specific steps to deploy this example using the SAP J2EE Engine Deploy Tool. For information on how to use the Deploy Tool to provide application components, to assemble, and to deploy, refer to the Deployment Manual.

Mapping the JSP

The JSPs and Servlet mapping – that is, the URL path relative to the applications URL – is done in the WAR “Mappings” tab. Select the WAR file from the “J2EEComponents” tab left-hand pane, and then select the “Mappings” tab. In the “Servlets” subtab, specify the “Servlet Name” field by entering YahooFinanceRetriever. Map this name to the “URL Pattern” field by entering /YahooFinance. Choose “Add.”

Note: A Servlet is mapped instead of a JSP because all JSPs, when coming to runtime, are translated into Servlets. The actual JSP cannot be run at all.

After specifying the mapping correctly, the WAR “Mappings” tab must look like this:

56/309


Mappings Tab

Setting the Environment Properties

The YahooFinance Stateless Session EJBean opens URL connections to the Internet site http://finance.yahoo.com and retrieves market summary data, such as S&P 500 or NASDAQ Volume data. Proxy settings are often required to establish an HTTP connection to the Internet. YahooFinance Stateless Session EJBean enables you to set proxy-related data using environment variables. To set proxy data, select the “YahooFinanceStatelessSessionBean” in the left-hand pane and then the “Environment” tab from the right-hand pane. To configure the proxy settings, specify proxyHost in the “Name” field and proxyPort in the “Value” field.

Proxy Data Name Type Value

proxyHost

Java.lang.String <your organization’s proxy host name>

ProxyPort

Java.lang.String <your organization’s proxy port >

57/309


Choose “Set.”

Note: Skip this step if there is no proxy server in your organization.

After setting the proxy data in the YahooFinanceStatelessSessionBean environment, the Deploy tool looks like this:

Environment Tab

Setting the Entity Beans’ Variables

For the MarketSummaryCMEntityBean to be able to interact with a database, you must specify which of the bean’s variables are going to be stored in the database table. To perform this task, select the MarketSummaryCMEntityBean in the “J2EEComponents” tab left-hand pane, and then the “Storage” tab from the right-hand pane. Set all the indicators in the “Store” pane.

58/309


Storage Tab

EJB References in the WAR

To find the EJBs inside the FacadeBean java code, there must be a mechanism to pinpoint each EJB in the application server’s directory tree, which is accessed using the JNDI interface.

Select MarketSummaryWAR.war from the “J2EEComponents” tab left-hand pane. Select the References→EJBean References subtab from the right-hand pane.

Fill in the fields with the following data:

YahooFinanceStatelessSessionBean Reference Data Name Value

Reference Name YahooFinanceRefName

Bean Type Session

Home Interface j2ee.marketsummary.YahooFinanceHome

59/309


Remote Interface j2ee.marketsummary.YahooFinance

Reference Link YahooFinanceStatelessSessionBean

MarketSummaryCMEntityBean Reference Data Name Value

Reference Name MarketSummaryRefName

Bean Type Entity

Home Interface j2ee.marketsummary.MarketSummaryHome

Remote Interface j2ee.marketsummary. MarketSummary

Reference Link MarketSummaryCMEntityBean

After entering each bean’s reference data, choose“Add.”

Note: Depending on the J2EE specification, you may not have to specify the “Reference Link” field.

In the current example, the name by which the Web components can lookup the EJB in the application server JNDI context must be specified in the “Reference Name” field.

After finishing the EJB reference configuration, the Deploy Tool must look like this:

60/309


References Tab

Deploying the EAR

Select MarketSummaryEAR.ear→MarketSummaryJAR.jar→MarketSummaryCMEntityBean from the left-hand pane of the “Deployer” tab. In the right-hand pane, select the “Storage” tab. Notice that the storage type is equal to the “RDBM Storage,” but the “Pool” and “Table” fields are not yet determined. Therefore, set up the database structure and the corresponding database pool as a resource first.

Setting up the Database Structure and Application Server’s Data Source (Database Pool)

The Market Summary application interacts with a database to perform read and write operations. Therefore, you must set up a data source in SAP J2EE Engine that corresponds to a RDBMS’s database to which Market Summary application has access. The database name is arbitrary. The structure is simple. It consists of one table. The table name is also arbitrary, but the table structure must comply with the following setting:

61/309


RDBMS’s Configuration

Object Name Description

Database Arbitrary <dbName> Data container in which market summary data is stored

DB2 COM.ibm.db2.jdbc.net.DB2Driver ORACLE oracle.jdbc.driver.OracleDriver SAP DB com.sap.dbtech.jdbc.DriverSapDB

JDBC Driver

Depends on the chosen database.

MSSQL com.inet.tds.TdsDriver DB2 jdbc:db2://<hostName>:<portNumber>/<dbName>

ORACLE Jdbc:oracle:oci8:@<hostName>:<portNumber>:<dbName>

SAP DB jdbc:sapdb://<hostName>/<dbName> Database URL

Depends on the chosen database

MSSQL Jdbc:inetdae:<hostName>:<portNumber>?database=<dbName>&sql7=true

Table Arbitrary <tableName>

Market Summary data is written to and read from this table by container-managed Entity Bean.

Table Configuration

Column Name Data Type Data Size Nulls SQL Type Primary Key

ORDER_ID BIGINT 19 No -5 Yes DATE DATE 10 No 91 No ITEM_NAME VARCHAR 128 Yes 12 No AMOUNT DECIMAL 30 Yes 3 No Description VARCHAR 1028 Yes 12 No

Create a database in an RDBMS of your choice (SAPDB, DB2, and so on). Name the database sample. Connect to the newly created database and create the MarketSummary table in it. In this document, a Microsoft SQL Server 7 database is used, and the data in the following table is used to set up the database:

Table Configuration Name Statement

62/309


MARKETSUMMARY

CREATE TABLE MARKETSUMMARY ( ORDER_ID int NOT NULL, DATE datetime NOT NULL, ITEM_NAME varchar(128) NULL, AMOUNT decimal(25, 6) NULL, DESCRIPTION varchar(1028) NULL PRIMARY KEY (ORDER_ID) )

Note: You may use another data definition language (DDL) according to the database used.

After finishing the database set up, start the SAP J2EE Engine Visual Administrator and connect it to SAP J2EE Engine. Choose View→Tab View. Select Services→dbpool→Server from the Visual Administrator left-hand pane. From the right-hand pane, choose the “Runtime” tab.

To set up a data source based on a relational database, specify the JDBC driver of the underlying database (in this example, Microsoft SQL 7 database is used). Choose “Add Driver” and type in the corresponding driver package string:

Add Driver

Choose “Ok.” A dialog box appears, in which you browse to the driver software.

When the driver is added successfully, choose Runtime→General from the right-hand pane and fill in the “Pool name,” “Database URL,” “User,” and “Password” fields with the following data:

Data Source Configuration at App Server Level (Admin Console) Parameter Name Parameter Value

Driver com.inet.tds.TdsDriver

Pool Name stkdata

Database URL jdbc:inetdae:localhost?database=sample&sql7=true

63/309


User sa

Password

After adapting the database connection and pooling settings, choose “Add” in the “Available Pools” pane.

Note: These steps can be successful only if:

• The RDBMS is up and running • The corresponding database exists • The database URL is correct – this URL is RDBMS specific • The userID and password are valid

DBPool Runtime Tab

Finishing the Deployment Process

In the Deploy Tool choose “Deployer.” Select the MarketSummaryEAR.ear→MarketSummaryJAR.jar→MarketSummaryCMEntityB

64/309


ean node from the left-hand pane. Choose “Storage” from the right-hand pane. Enter the storage related data in the corresponding fields.

Storage Tab

Note: The column names of “orderid” and “itemName” (the CMEntityBean’s field names) must be changed manually to “order_id” and “item_Name” (adaptation with the names of the corresponding columns in the database table).

When the pool-related information is set, choose “Find Methods” and select the “findByDate(java.sql.Date)” finder method in the “Methods” pane. In the “Criteria” pane, type “date=$1” (without quotation marks).

Note: For information on how to complete the deployment process, refer to the Deployment Manual.

65/309


CD Collection

Overview

This example enables you to create scalable and modular applications using different J2EE components. The whole process is explained in the sections below.

The CD Collection example enables you to search the CD Collection by selecting different CD attributes:

• CD name • The performing artist • The year of the CD release

It also enables you to add a new entry (a new CD) to the collection. The search is performed using a pattern match in a local database.

Application Components

The application is designed according to the MVC pattern (Model View Controller). In our example it consists of three different components – view (SearchCollection.jsp, Entry.html), controller (SearchCollectionBean.java, CDData.java) and business logic (CDWriteBean.java). These components are summarized in detail in the Application Design and Development part.


Entry.html Expects the user’s input of a search

pattern or attributes of a CD to be stored in the database.

View-related, static component.

SearchCollection.jsp Generates the client view of the application. Instantiates a JavaBean and invokes CDCatalog’s functions.

View-related, dynamic component that can be upgraded easily without influencing the application logic.

SearchCollectionBean.java

The JavaBean’s class, which has control over the model layer.

Control-related component

66/309


CDData.java A class encapsulating the attributes of a CD.

Control-related component

CDWrite.java An EJB class representing the data in the database. CDWrite is an entity bean with bean-managed persistence.

Model-related component.

Application Design and Development

The application has four main components:

• An HTML page expecting the user’s input and passing the data to the controller

• A jsp page, which presents the result view of the application • Graphical components (jpeg and gif) • A jar file containing one JavaBean, the CDData.java Java class and an

Entity EJB

67/309


Application Structure

SearchCollection.jsp

SearchCollection.jsp is the visual environment in which results from queries and database updates are visualized. Two general options are provided:

• Insert a CD data into a database • Search a CD by a specified criteria

You can choose from different search criteria by selecting the corresponding option. The types of search criteria are:

68/309


• By CD’s Title • By Performing Artist • By Year Of Release • Get All Entries

If an error occurs while adding the data, an appropriate message is displayed. You are informed that the CD was added successfully to the collection.

When called, the SearchCollection.jsp instantiates the SearchCollection.java JavaBean that holds the application logic.

SearchCollectionBean.java

This JavaBean possesses business methods that call methods of the entity bean remote interface. Therefore, special clients’ requirements can be met, concerning the modification of the example’s logic. You can search a database to find the desired data about a particular CD:

Method Description

public Vector getByCdName(String name);

Returns data about the specified CD; searches the database by CD name.

public Vector getByArtist(String artist);

Returns data about the specified CD; searches the database by performing artist.

public Vector getByReleaseYear(String releaseYear);

Returns data about the specified CD; searches the database by year of release.

public Vector getAll(); Returns data for all the CDs in the database.

Vector object, returned by these methods, represents all CDs that match a particular criteria specified by the user (in the SearchCollection.jsp). Vector contains CDData objects, which store the CD data.

69/309


CDDate.java

This class is a complex representation of a CD object. It stores data about a particular CD and is used for communication between the jsp file and the database.

Method Description

public String getCdName();

Returns the name of the CD as a String object.

public void setCdName(String cdName);

Specifies a CD name.

public String getArtist(); Returns the name of the performing artist as a String object.

public void setArtist(String artist);

Specifies a performing artist’s name.

public String getReleaseYear();

Returns the release year of the specified CD.

public void setReleaseYear(String releaseYear);

Specifies release year for the CD.

CDWriteBean.java

CDWriteBean.java is a bean-managed EJB that has direct access to the database. CDWriteBean.java interacts with the SearchCollectionBean.java to perform the database search. In this way, greater flexibility and manageability of the development process is achieved, dividing the application’s logic among different modules. It also provides for updates and queries to the database. The following methods execute this process:

Method Description

public Enumeration ejbFindByArtist(String art);

Retrieves data about the specified CD; searches the database by performing artist.

70/309


public Enumeration ejbFindByCdName(String cdname);

Retrieves data about the specified CD; searches the database by CD name.

public Enumeration ejbFindByReleaseYear(String relYear);

Retrieves data about the specified CD; searches the database by year of release.

These methods’ functions correspond to those in the SearchCollectionBean.java. The difference is that they operate directly with the database when inserting or retrieving CD data.

71/309


Statistical Calculator

Overview

Statistical Calculator is an example that encapsulates simple application logic implemented in J2EE components. This application enables you to perform the following statistical calculations for a specified set of decimal numbers, divided by semicolons:

• Sum • Mean value • Mean square deviation

Application Components

The application is designed in accordance with the MVC (Model View Controller) pattern. It consists of three basic types of components – view-related (StatisticalCalculator.jsp), control-related (RequestControllerBean. java), and model-related (IODataBean.java, Calculator.java). These components are summarized in the table below.


StatisticalCalculator.jsp

Generates the client view of the application. Instantiates JavaBean components and invokes calculator functions.

View-related, dynamic component that can be updated easily without affecting the application logic.

RequestControllerBean. java

Encapsulates and controls calculator functions.

Control-related component.

IODataBean.java Main data structure for exchange of application data between layers.


Calculator.java The calculator functions implementation class.


72/309


Application Design and Development

This application includes the following elements:

• JSP page (StatisticalCalculator.jsp), which represents the entry and the result view of the application

• A JAR file containing JavaBeans and additional classes that encapsulate the application functions

• Graphical and style components (GIF and CSS)

The following graphic shows the relations between the components:

StatisticalCalculator.jsp

StatisticalCalculator.jsp is the central element for this application. It presents the client view of the application and is used to obtain the input stream to be processed further by the JavaBeans components.

The code of the JSP begins with an import directive:

73/309


<%@ page import="j2ee.statistical_calculator.*"%>

This statement implies that the JSP page can invoke methods on all classes included in package com.inqmy.qa.examples.statistical_calculator. When StatisticalCalculator.jsp is invoked, two JavaBeans (IODataBean and RequestControllerBean) are also loaded and instantiated using a standard JSP action:

<jsp:useBean name=”…” scope=”…” class=”…” />

This action is used to associate an instance of the JavaBean specified by its implementation class with a particular name that is used further for identification. The scope parameter defines the behavior of the name attribute – that is, it describes the namespace, and the lifecycle of the object reference associated with the name attribute. In this case, the scope attribute is assigned the value session. Session scope implies that the named object (JavaBean instance) is available within the current HTTPSession object.

When the instance of IODataBean is created, the <jsp:setProperty> tag must be specified to enable the JSP to invoke set methods of this JavaBean:

<jsp:setProperty name="iodata" property="*" />

Because the instances of IODataBean (named iodata) and RequestControllerBean (named processor) to be used by the JSP are already created, StatisticalCalculator.jsp can invoke methods on these beans:

<% processor.setIoData(iodata); iodata = processor.getIoData(); %>

The <%…%> tags are used to denote scriptlets, which are defined in JavaServer Pages Specification as elements that contain any code written in the declared script language (Java). In this case, two methods of RequestControllerBean are invoked – setIoData and getIoData. The setIoData method is passed an iodata object as an argument – that is, this is the IODataBean instance with which StatisticalCalculator.jsp is associated for the corresponding session. This bean keeps the input data specified in the JSP.

The input data is processed using the HTTP GET request:

<FORM name="Calculator" action="" method="GET">… </FORM>

This is a standard HTML form. The method argument, which is specified here, defines the HTTPServlet method to be used for processing this request

74/309


(doGet() in this case). You can also use the POST method here. The two options differ in the way they are processed. When GET is the method specified, the input information is appended to the URL, which on most receiving systems becomes the value of the environment variable QUERY_STRING. In the opposite case, the input information is sent in a data body that is available with the data length set in the environment variable CONTENT_LENGTH.

The result view of the JSP is invoked, with the following code included as a scriptlet:

<% if (request.getParameter("Calculate.x")!=null) { %> … <% else{ %> . . . <% if (request.getParameter("Help.x")!=null) { %> … <% else{ %> . . .

The code above represents the two available options:

• Calculation based on the input string • Invoking help message

Two conditions are considered for the option when you have selected the calculation option:

<% if (iodata.isOk()) { %> <TR> <TD class=rowleft width=25%><jsp:getProperty name="iodata" property="functionName" /> = </TD> <TD class=rowright width=75%><jsp:getProperty name="iodata" property="resultString" /></TD> </TR> <TR> <TD class=rowleft width=25%>for given set of values = </TD> <TD class=rowright width=75%><jsp:getProperty name="iodata" property="inputString" /></TD> </TR> <jsp:setProperty name="iodata" property="inputString" value="" /> <% } else { %> <TR> <TD class=rowleft width=25%>Error message:</TD> <TD class=rowright width=75%><jsp:getProperty name="iodata" property="errMessage" /></TD>

75/309


</TR> <% } %>

The JSP invokes the isOk() method of IODataBean, which checks if the input data is parsed correctly. If true, the calculations are done. If there is error validating and parsing the input data, an error message is displayed.

The result from the calculations is stored in the IODataBean instance. The output is converted to a String. To get and display it, the following action is used:

<jsp:getProperty name="iodata" property="functionName" /> <jsp:getProperty name="iodata" property="resultString" />

The bean instance that holds the output is again specified by the name it has been given using the jsp:useBean action (iodata).

IODataBean.java

Class IODataBean implements java.io.Serializable. Its instances are the objects that hold the input data. This class communicates with StatisticalCalculator.jsp to get the input data and to provide the result of the calculations. This is done using the following methods:

Method Description

public int getFunctionNo()

Returns the number identifier of a function.

public void setFunctionNo(int argFunctionNo)

Sets function number identifier as an integer.

public String getFunctionName()

Returns the name identifier of a function.

public void setFunctionName(String argFunctionName)

Sets name identifier for a function.

public void setFunctionNo(String argFunctionNoStr)

Sets function number identifier as a string. It must be numeric to be parsed correctly; otherwise, an exception is thrown.

76/309


public String getInputString()

Returns the input string from the JSP file.

public void setInputString(String argInputString)

Sets the input data string.

public String getResultString()

Returns the result string obtained from the calculations.

protected void setResultString(String argResultString)

Sets the result string.

public boolean isOk() Checks if the input data is parsed correctly.

public void setOk (boolean argOk)

Sets boolean value (true or false) for a variable that specifies if the input data is parsed correctly.

RequestControllerBean.java

Class RequestControllerBean implements java.io.Serializable. This element implements the control interface between the client view of the application and the methods that perform the actual calculations. It retrieves the data that IODataBean instances hold, and passes it to the instances of class Calculator. RequestControllerBean provides the following methods:

Method Description

public IODataBean getIoData()

Returns a reference to an instance of IODataBean. Within this method, the constructor of IODataBean is invoked to create a new object. A try-catch block is then executed. If the input data is parsed correctly, the corresponding calculations are done. If there is an error validating and parsing the input data, an exception is thrown and the Ok variable is set to false (ioData.setOk(false);).

public void setIoData (IODataBean argIOData)

Sets the reference to IODataBean instance to a specified value.

private Calculator getCalc()

Returns a reference to an instance of Calculator.

77/309


Calculator.java

This class encapsulates the calculation logic of the application. It provides methods that perform the actual calculations on the basis of the input data:

Method Description

protected void performCalculation()

Provides the logic of performing a calculation. This logic involves validating and parsing the input data; defining the function to be executed (using switch clause) and invoking the method that executes it, and setting the result string.

protected IODataBean getIoData()

Returns reference to an instance of IODataBean.

protected void setIoData(IODataBean argIoData)

Sets reference to an instance of IODataBean.

private void validateAndParseInputData()

Performs check and parses the input data. This method checks if the specified function number identifier is valid – that is, if a particular function is associated to this number – and if the specified number is invalid, a CalculatorException is thrown. This method also parses the input string to float data type and adds the items to an array.

private float sum() Returns the sum of the items in the array.

private float meanValue()

Returns the mean value calculated for the items in the array.

private float meanSquareDeviation()

Returns the mean square deviation calculated for the items in the array.

78/309


Chapter 3 Developers Tasks

• Configuring JBuilder Plug-in for Application Deployment and Debugging

• Lookup resources over the JNDI

79/309


Configuring JBuilder Plug-in for Application Deployment and Debugging

Overview

This Plug-in is written according to Borland’s OpenTools API for JBuilder 5.0 and provides integration between JBuilder 5.0 and SAP J2EE Engine 6.20 and higher. It enables developers to deploy applications written with JBuilder 5.0 directly on SAP J2EE Engine. Furthermore, this Plug-in enables you to run and debug Web applications from the JBuilder 5.0 environment on SAP J2EE Engine.

Compatibility

This Plug-in is compatible with SAP J2EE Engine 6.20 Stand-alone version, or higher.

How to Install the Plug-In

To install the Plug-in, you need JBuilder 5 and SAP J2EE Engine 6.20 Stand-alone version, or higher, installed.

Copy the SAPJ2EEEngineJBuilderPlugin.jar from <SAPj2eeEngine_install_dir>/tools/JbuilderPlugin and paste it in the <JBuilder_install_dir>/lib/ext directory.

Copy the inqmyxml.jar from <SAPj2eeEngine_install_dir>/deploying/lib and paste it in the <JBuilder_install_dir>/patch directory.

Setting SAP J2EE Engine as Your Default Web Server

To configure and use the plug-in, complete the following steps:

80/309


Step 1 – Modifying JBuilder 5.0 Tool Properties

Start JBuilder 5.0. Choose Tools→Enterprise Setup. A dialog box appears.

Note: Please make sure you have opened a project in JBuilder. Otherwise, the “Tools” menu will not be accessible.

Select the “Application Server” tab. Choose the “SAP J2EE Engine 6.20” subtab. Browse to select the SAP J2EE Engine installation directory.

Enterprise Setup

Choose “OK” to confirm your choice, and exit the “Enterprise Setup” dialog box.

Step 2 – Modifying JBuilder 5.0 Project Properties

You must set SAP J2EE Engine as your default Web server to be able to deploy and debug Web applications.

81/309


To modify JBuilder’s project properties, choose Project→Project Properties. Select the “Servers” tab from the “Project Properties” dialog box. Choose “…” and select “SAP J2EE Engine 6.20” from the dialog box that appears.

Select Application Server

To edit the application server properties, choose “Edit.” When you finish modifying the server properties, choose “OK” from the “Select Application Server” dialog box for the changes to take effect.

The SAP J2EE Engine 6.20 appears in the “Project Properties” dialog box.

82/309


Project Properties

To make the application server your default Web server, set the “Application server is Web server” indicator. Choose “OK” to finish modifying the project properties.

Note: Follow the steps bellow to run SAP J2EE Engine 6.20 from within JBuilder. Please note, that the following instructions are useful only when you start the server in JBuilder environment. They have no relation to the debugging or deploying processes.

• Select Project->Project Properties • Select the “Servers” tab from the “Project Properties” dialog box.

Choose “…”, select “SAP J2EE Engine 6.20” and choose “Edit.” A dialog box appears. Enter the following properties in the “VM parameters” field: -Dorg.omg.CORBA.ORBClass=com.inqmy.system.ORBProxy -Dorg.omg.CORBA.ORBSingletonClass=com.inqmy.services.iiop.internal.ORB -Djavax.rmi.CORBA.PortableRemoteObjectClass=com.inqmy.system.Port

83/309


ableRemoteObjectProxy -Djavax.rmi.CORBA.UtilClass=com.inqmy.system.UtilDelegateProxy -Dredirect.input=true

• Select “Working Directory” from the “Paths” tab and browse to the <SAPj2eeEngine_install_dir>/alone directory

• Select the “Required Libraries” subtab from the “Paths” tab and add a new library containing the jar files from the <SAPj2eeEngine_install_dir>/alone/system-lib/ directory

• Select Run->Run Project

Starting SAP J2EE Engine in JBuilder 5.0

After you have developed your Web application using JBuilder 5.0, you must start SAP J2EE Engine as your default Web server to debug and deploy the application. There are two ways to start SAP J2EE Engine in JBuilder 5.0:

• Choose Run→Run Project from the JBuilder 5.0 menu bar – this command starts SAP J2EE Engine in its common mode – that is, without its specific debug features. When the SAP J2EE Engine system is started, you can deploy the application using SAP J2EE Engine.

• Choose Run->Debug Project from the JBuilder 5.0 menu bar – this menu starts SAP J2EE Engine in debug mode – that is, along with the server, some additional properties for debugging are started.

Deploying Applications with JBuilder 5.0

This step describes how to deploy applications developed in JBuilder 5.0 on SAP J2EE Engine. Before starting the deployment process, make sure that SAP J2EE Engine is already running in JBuilder.

Note: Before starting the deployment process the name of the <web><context-root> tag in application.xml must be changed to correspond to the name of the Web application that creates the WAR file.

Deployment

Right-click the EAR file you want to deploy. A menu group named “SAP J2EE Engine Application Deployment” is available in the pop-up menu that appears:

84/309


SAP J2EE Engine Application Deployment

Choose SAP J2EE Engine Application Deployment→Deploy to start the SAP J2EE Engine Deploy Tool.

85/309


Deploy Tool

Choose to connect to SAP J2EE Engine, and then select to deploy your Web application.

Another way of starting the deployment process is to select Tools→SAP J2EE Engine Application Deployment from the JBuilder 5.0 menu bar. A dialog box with a list of available application archives appears:

86/309


Select Ear File

Select the archive you want to deploy, and choose “OK.”

Note: For further information on how to deploy using SAP J2EE Engine Deploy Tool, refer to the SAP J2EE Engine Documentation.

Redeployment

Choose SAP J2EE Engine Application Deployment→Redeploy to start the redeployment process.

87/309


Redeployment

To continue with the redeployment process, use the options described in the Deployment section.

Running and Debugging Applications with JBuilder 5.0

Make sure that the application you want to debug is already deployed. SAP J2EE Engine must not be started externally because JBuilder starts it internally when the JSP is started.

Right-click the file, and choose Web Run or Web Debug from the pop-up menu that appears.

Additional Options for Optimizing the Debugging Process

You can enhance the SAP J2EE Engine debugging functions by setting some additional properties in SAP J2EE Engine Visual Administrator.

88/309


To define these additional properties, start SAP J2EE Engine Visual Administrator. Make sure that you are in Cluster view mode (that is, make sure that on the toolbar is selected). Choose Cluster→Server→Services→Servlet_jsp from SAP J2EE Engine Visual Administrator left-hand pane. Choose “Properties” from the right-hand pane. The properties that help you to enhance the debugging process are:

• CompileOnStartUp – specifies whether to compile JSPs on server startup or during the J2EE application deployment. It has a boolean value. If set to true, the JSP file compiles automatically after deploying. The system uses the CLASS file for debugging.

• CompilerDebuggingInfo – specifies the amount of debug information the compiler generates. It has a boolean value. If set to true, the compiler generates more debug information. If this property is set to false, the local variables’ values are invisible in debug mode.

Select the property you want to modify and change its value in the “Value” field at the bottom of the right-hand pane. Choose “Add.” For the changes to take effect, choose (Save Properties) on the toolbar.

89/309


Lookup Resources over the JNDI

This section describes how to use the functions provided by the JNDI system in SAP J2EE Engine.

Services Lookup

The objects representing the services are bound in the naming at start up. The class, whose instances are bound, implements the com.inqmy.frame.ServiceReference class. After lookup, the getServiceInterface() method of the ServiceReference must be invoked. It returns a remote interface, which is registered by the service in the frame. The objects of ServiceReference type are bound and looked up in the root of the naming system. Their names are identical to the services names. Since the application has access to an offset context, it is necessary to create an initial context with property “domain” and value “true”. A short example follows:

package com.inqmy.demo; import java.util.*; import java.rmi.*; import javax.naming.*; import com.inqmy.services.deploy.DeployService; import com.inqmy.frame.ServiceReference; /** * Class demonstrating the lookup of services * * @version 6.20 */ public class ServiceLookup { public static void main(String[] args) { // Initialize the properties needed for InitialContext Properties p = new Properties(); p.put(Context.INITIAL_CONTEXT_FACTORY, "com.inqmy.services.jndi.InitialContextFactoryImpl"); p.put("domain", "true"); // Get the naming context try { System.out.println("Obtaining a naming context ..."); Context ctx = new InitialContext(p); System.out.println("Done.\n");

90/309


// Get the Deploy service System.out.println("Getting the Deploy service ..."); DeployService ds = (DeployService) ((ServiceReference) ctx.lookup("deploy")).getServiceInterface(); System.out.println("Done.\n"); // Print the available containers on all cluster elements String[] containers = ds.listContainers(null); System.out.println("Listing containers available :"); for(int i=0; i < containers.length; i++) { System.out.println(" container[" + i + "] = " + containers[i]); } } catch (NamingException ne) { System.out.println("Exception obtaining naming context :"); ne.printStackTrace(); } catch (RemoteException re) { System.out.println("Exception when calling listContainers method :"); re.printStackTrace(); } } }

Binding Local and Global Objects. Persistent and Non-Persistent Statute

A local object is an object, which has different values on different server nodes. On the opposite, the global object has single value within the whole cluster. The services (service references) are bound locally in the naming system as remote objects with non-persistent statute. Non-persistent statute means that after a server node restart, the objects are erased.

Typically the objects are global. There are no any peculiarities in performing bind or lookup operations on global objects.

The local objects are two types:

• Serializable with persistent statute • Serializable, non-serializable or remote with non-persistent statute.

In the first case the syntax for binding and looking up is “+/” or “+xxx/” as prefixes to the names, which are passed as arguments, where xxx is the cluster id of a server node. An example is provided below:

91/309


package com.inqmy.demo; import java.util.*; import javax.naming.*; /** * Class demonstrating the different object types * * @version 6.20 */ public class ObjectTypes { public static void main(String[] args) { // Initialize the properties needed for InitialContext Properties p = new Properties(); p.put(Context.INITIAL_CONTEXT_FACTORY, "com.inqmy.services.jndi.InitialContextFactoryImpl"); p.put("domain", "true"); // Get the naming context try { System.out.println("Obtaining a naming context ..."); Context ctx = new InitialContext(p); System.out.println("Done.\n"); System.out.println("Binding global object ..."); ctx.rebind("GlobalObject", new String("This is global object ")); System.out.println("The global object contains : " + (String) ctx.lookup("GlobalObject")); System.out.println(); System.out.println("Binding local object ..."); ctx.rebind("+/LocalObject", "This one is a local object !"); System.out.println("The local object contains : " + (String) ctx.lookup("+/LocalObject")); System.out.println(); System.out.println("Binding non-serializable object ..."); ctx.rebind("^/NonSerializable", new Object()); System.out.println("The non-serializable object is : " + ctx.lookup("NonSerializable")); } catch (NamingException ne) { System.out.println("Exception occured :"); ne.printStackTrace(); } } }

92/309


Lookup from a Different Cluster

Lookup from a different cluster is performed as described above. The only difference is the way the initial context is obtained, since a P4ObjectBroker object must be specified for the factory. Two ways for obtaining an initial context with remote broker are provided. In the first case an InitialContextFactoryImpl class as a factory is used. In the properties using “force_remote” with “true” value must be specified in order to use remote broker. In the other case RemoteInitialContextFactoryImpl factory is used, without having to set any specific properties. When obtaining a remote context, the root context is returned as initial, regardless of whether the property “domain” is specified. An example showing the process is provided below:

// Initialize the properties needed for InitialContext Properties p = new Properties(); p.put(Context.INITIAL_CONTEXT_FACTORY, "com.inqmy.services.jndi.InitialContextFactoryImpl"); p.put(Context.PROVIDER_URL, "here goes the remote cluster's URL"); p.put("force_remote", "true"); // Get the naming context try { System.out.println("Obtaining a naming context ..."); Context ctx = new InitialContext(p); System.out.println("Done.\n"); System.out.println("Lookuping the DEPLOY service as object : " + ctx.lookup("deploy")); } catch (NamingException ne) { System.out.println("Exception occured :"); ne.printStackTrace(); }

Note: RemoteInitialContextFactoryImpl can be used only be applications and not by services.

93/309


Chapter 4 Services Guide

94/309


Overview

Services in SAP J2EE Engine are divided into two groups – core and additional. Core services are a part of the system kernel, as they help the system function. Additional services use core modules to provide specific application server functions.

The Services Guide explains the functions of each SAP J2EE Engine service. It provides descriptions of the main features of both core and additional, J2EE and SAP J2EE Engine – specific service modules. In addition, it specifies service interfaces that can be accessed and used by clients. The descriptions of the services are as follows:

• Overview – provides an overview of the specific functions of the particular module, as well as an explanation of its relations to other modules within SAP J2EE Engine

• Interfaces – an introduction to the service interface(s) that is bound in naming and can be used by clients. Comprehensive descriptions of the interfaces and their methods are provided. This section is not common for all services, because a part of them (for example, core services) do not provide interfaces that are directly accessible by clients.

• Example – examples are provided for all services that have directly accessible service interfaces. This part contains descriptions of the example locations and classes.

95/309


Admin Service

Overview

Admin Service is a distributed service that enables remote administration of the cluster and control of the modules running on the cluster nodes. It provides information about all managers, information and administration of all services, and monitoring of the whole cluster for further events. Admin Service performs all Visual Administrator tool functions.

Interfaces

RemoteAdminInterface

This is a remote interface that performs the connection between the client and the Admin service. It provides the server information and administration and is returned by ServiceReference when a lookup operation for “admin” is performed.

public AdminFramework getAdminFramework()

This method returns the AdminFramework interface implementation that provides for administration of the whole server and information about all server managers. The methods of the AdminFramework interface are provided following the description of this method.

• Return values o Returns the AdminFramework interface implementation

AdminFramework Interface

This interface administers SAP J2EE Engine:

• getAllManagers(int clusterID) – returns an array of all managers names of a specific cluster element

• getAllManagersInCluster() – returns a two-dimensional array of strings containing all managers of all cluster elements

• getClusterInfo() – returns a two-dimensional array of strings with all cluster elements information

96/309


• getClusterName() – returns the name of the cluster element • getClusterElementInfo(int clusterID) – returns an array of

information about a specific cluster element • dropDown(boolean restart) – shuts down or restarts the whole cluster • shutDown(int clusterID) – shuts down a specific cluster element. If

the ID of the element is 0, this process refers to the whole cluster. • reboot(int clusterID) – reboots a specific cluster element. If the ID

of the element is 0, this process refers to the whole cluster. • getManagerProps(int clusterID, String managerName) – returns the

properties of a specific manager • changeManagerProps(int clusterID, String managerName, Properties

properties) – returns true if the properties change of specific manager is successful, or reboots the whole cluster element

• getManagerStatus(int clusterID, String managerName) – returns in percentage terms the specific manager working status

• getManagerDiagramCount(int clusterID, String managerName) – returns the number of specific manager diagrams. The maximum number of diagrams for a manager is 3 and the maximum number of statistics for a diagram is 5 (example: statistic for number of running threads)

• getManagerStatisticName(int clusterID, String managerName, byte

diagram) – returns an array of the statistics names • getManagerMaxStatisticValues(int clusterID, String managerName,

byte diagram) – returns an array of maximum values for a specific statistic

• getManagerStatisticValues(int clusterID, String managerName,

byte diagram) – returns an array of the current statistic values to the specific diagram

public AdminServiceManager getAdminServiceManager()

This method returns AdminServiceManager interface implementation, which provides for information and administration of all server services. The methods of the AdminServiceManager interface are provided following the description of this method.

• Return values o Returns AdminServiceManager interface implementation

AdminServiceManager Interface

This interface manages SAP J2EE Engine Services:

97/309


• getAllServices(int clusterID) – returns two-dimensional array of strings that contains the whole info about all services for this cluster element. This information is unique for each service – name, status (running or not), start up mode (always, disabled), container persistency, core or not.

• getServiceInfo(int clusterID, string ServiceName) – returns information about specific service

• startService(int clusterID, String sName) – starts cluster element specific service

• stopService(int clusterID, String sName) – stops cluster element specific service

• getServiceProperties(int clusterID, String serviceName) – returns specific service properties

• changeServiceProperties(int clusterID, String serviceName,

Properties sp) – changes specific service properties runtime on given cluster element. Returns a boolean value. If it is true, a cluster element reboot is required for core service and a service reboot for additional one.

• getServiceRuntimeReference(String serviceName, int clusterID) – returns the Runtime control, if it exists

• getAllServiceDescriptors(int clusterID) – returns an array of DeployedServiceDescriptor of all services

• getServiceDescriptor(int clusterID, String sName) – returns the DeployedServiceDescriptor of a specific service

• changeServiceDescriptor(int clusterID, String serviceName,

DeployedServiceDescriptor dsd) – changes runtime deployed service descriptor on specified cluster element

• getLogViewer() – returns an interface to establish a connection to cluster Log Manager

AdminLogViewer Inteface

AdminLogViewer interface provides LogViewer objects that are used for retrieving logs of services, managers or whole cluster nodes. The proper service, manager or cluster node to retrieve logs for is determined by initializing the AdminLogViewer with the corresponding cluster ID.

AdminLogViewer interface provides the following methods:

• getAllDestinations() – returns an array of all destination IDs. A destination may be a single service, a single manager or a whole cluster node.

98/309


• getDestinationLogs(long destID) – returns the logs of the specified destination

• setIDs(int clusterId) – by using this method you can determine the cluster element for which logs are retrieved. The method itself performs initialization of AdminLogViewer. When method is called with –1 parameter, logs for all cluster elements are retrieved

• setIDsWait(int clusterId) – this methods does the same thing as the setIDs(int clusterId) method but does not start a new thread for this operation

• getNextServiceLogs(byte logType, String serviceName, int count)– retrieves the specified amount of logs of the specified service that match the specified log type

• getNewServiceLogs(byte logType, String serviceName) – retrieves the logs of the specified service that match the specified log type

• getNextManagerLogs(byte logType, String managerName, int count)- retrieves the specified amount of logs of the specified manager that match the specified log type

• getNewManagerLogs(byte logType, String managerName) - retrieves the logs of the specified manager that match the specified log type

• getNextServicesLogs(byte logType, int count) - retrieves the specified amount of logs of all services that match the specified log type

• getNewServicesLogs(byte logType) - retrieves the logs of all services that match the specified log type

• getNextManagersLogs(byte logType, int count) - retrieves the specified amount of logs of all managers that match the specified log type

• getNewManagersLogs(byte logType) - retrieves the logs of all managers that match the specified log type

• getNextClusterLogs(byte logType, int count) - retrieves the specified amount of logs for the whole cluster that match the specified log type

• getNewClusterLogs(byte logType) - retrieves the logs for the whole cluster that match the specified log type

• startCheck(LogObject lo) – this method checks if new LogObjects are created and stores the log information in the corresponding LogViewer object. It is referred to as setting online log retrieval.

• startLevelCheck() – performs checks on the log level and retrieves only those logs with level equal or lower that the level specified

• stopCheck() – this method stops the online log retrieval • stopLevelCheck() – this method stops performing checks for the log

level of the logs to be retrieved • free() – releases all file references and pointers

99/309


public AdminServiceManager getAdminServiceManager(AdminCallback ac)

This method returns AdminServiceManager interface implementation, which provides for information and administration of all server services and monitoring of the whole server. The methods of the AdminServiceManager interface are provided above.

• Arguments o AdminCallback ac – this method takes as argument AdminCallback

interface implementation. It is described below. • Return values

o Returns AdminServiceManager interface implementation

AdminCallback Interface

This interface registers callbacks for monitoring cluster events. To get specific information by monitoring the cluster, you must overwrite the corresponding methods in the AdminCallback interface:

• updatedServiceStatus(String sName, int serverID, int status) – is invoked when a specific service has changed its status

• updatedServiceDescriptor(String sName, int serverID,

DeployedServiceDescriptor dsd) – is invoked when a specific service descriptor is updated

• updatedServiceProperties(String sName, int serverID, Properties

props) – is invoked when a specific service property is updated • addedServer(int serverID, String name) – is invoked when a server

node has been added • removedServer(int serverID, String name) – is invoked when a

server node has been removed • addedService(String sName, int serverID, String serverName) – is

invoked when a service has been added • removedService(String sName, int serverID, String serverName) –

is invoked when a service has been removed • updatedManagerProperties(String managerName, int serverID,

Properties props) – is invoked when the specific manager properties has been changed

• updatedUserTree() – is invoked when the users tree has been updated

100/309


public UserNode getTree()

This method returns the implementation of UserNode interface that represents the hierarchy between users and groups in the storage. Its methods are described below:

• setParents(UserNode[] parents) – sets handlers to the direct parents of the user or group

• setChildren(UserNode[] children) – sets handlers to the direct children of the group

• getName() – returns the name of the user • getParents() – returns an array with handlers to all direct parents of

the user or group • getChildren() – returns an array with handlers to all direct children of

specific group • getSID() – returns the ID of specific user or group • isUser() – returns true if the object represents a user

public int getCurrentID()

This method returns the ID of the current cluster element:

• Return values o Returns the current cluster element ID

public Properties getStatus()

This method returns java.util.Properties concerning the server status:

• Return values o System properties (System.getProperties()) o The server.started property – its value is set to true after all

server managers and services are loaded successfully, and confirms that the application server is started.

Example

The Admin example must implement the functions of RemoteAdminInterface and overwrite the process() method defined in the ExampleInterface. The following operations can be performed:

101/309


• changeServiceProps(String serviceName, String key, String

newValue) – changes the value of specific service property

public void changeServiceProps(String serviceName, String key, String newValue) { int currentID = adminService.getCurrentID(); Properties servProps = adminSM.getServiceProperties(currentID, serviceName); servProps.put(key, newValue); adminSM.changeServiceProperties(currentID, serviceName, servProps); }

• serviceInfo(int clusterElID) – prints all services and provides information, such as: status (started or stopped), start up mode, and is the service core or not

public void servicesInfo(int clusterElID) { String[][] services = adminSM.getAllServices(clusterElID); System.out.println("Listing all services:"); for (int i = 0; i < services.length; i++) { System.out.println("Info about " + services[i][0]); System.out.println("\tStatus: " + services[i][1]); System.out.println("\tStartup mode: " + services[i][2]); System.out.println("\tCore: " + services[i][3]); } }

• clusterInfo() – provides information about the cluster elements – ID, host, port, and if the cluster element is primary

public void clusterInfo() { String[][] info = adminFrame.getClusterInfo(); String clusterName = adminFrame.getClusterName(); System.out.println("\t***** Info about " + clusterName + " *****\n"); for (int i = 0; i < info.length; i++) { System.out.println("Info about " + info[i][0]); System.out.println("\tID: " + info[i][1]); System.out.println("\tHost address: " + info[i][2]); System.out.println("\tConnection port: " + info[i][3]); System.out.println("\tType of element: " + info[i][4]); } }

102/309


Appclient Service

Overview

Appclient Service invokes the already deployed application clients at their main methods and runs them on separate Java™ virtual machines until these machines are terminated.

Appclient Service provides a container and is used by the Deploy Service during the EAR component deployment, if there is an application client JAR in it. Deploy Service consults with Appclient Service about the way the application client is deployed.

A client can access an already deployed application by invoking Appclient Service interface. This interface executes the runClient() method, which starts the application client on a separate Java™ virtual machine (JVM).

Interfaces

AppclientRuntimeInterface

Appclient Service interface implementations can be registered both as a RuntimeInterface for administering Appclient Service and as a ServiceInterface returned by ServiceReference when the application client is looked up from the naming. This interface provides methods for running or stopping application clients that have been deployed previously on the server.

Client processes can receive additional properties depending on the user’s environment. The user can (for example) change the InitialContextFactory by passing additional properties that contain the Context.INITIAL_CONTEXT_FACTORY property set to a specific value.

Additional classpaths can also be set to the application client. The launcher code must first set Appclient Service property com.inqmy.services.appclient.classpathNumber to a specified number according to the number of classpath tokens, which the code passes to the application client. In the property file, a specified number of tokens must be set in the following way:

103/309


classpathToken_1=... classpathToken_2=... classpathToken_3=... ... ... ... classpathToken_n=...

Where n is the number of tokens set using the com.inqmy.services.appclient.classpathNumber property. The token value must be a single directory or a file that must be added to the application client’s classpath.

The interface syntax is:

public interface AppclientRuntimeInterface extends RuntimeInterface {

runClient(String appname, String args)

This method runs an application client on a different JVM, passing the user-provided arguments to the application client’s main class. The method does not wait for the process produced for the application client to finish. Waiting can be performed subsequently using the stopClient() method.

• Arguments o appname – the application client display name (not the display name

of the whole application) o args – the arguments passed to the application client’s main class

• Return values o return – a unique clientId that is used later to identify the

running application client’s process when stopping or destroying the process

• Exceptions o RemoteException – this exception is thrown if problems occur while

running the application client

The method syntax is:

public int runClient(String appname, String args) throws RemoteException;

processClient(String appname, String args, String dumpFileName)

This method runs an application client on a different JVM, passing the user-provided arguments to the application client’s main class. The method waits

104/309


for the process to finish and then returns its exit code. The process output is redirected to a specified file and errors are redirected to a different file with the same name, but with the .errors appendage.


of the whole application) o args – the arguments passed to the application client’s main class o dumpFileName – the file name to which the output is redirected

• Return values o return – the produced process exit code


running the application client


public int processClient(String appname, String args, String dumpFileName) throws RemoteException;

stopClient(int id, String dumpFileName, boolean destroy)

This method waits for a specific process denoted by the unique ID returned by runClient() method to finish and then returns its exit code, or simply destroys the specified process. The process output is redirected to a specified file and errors are redirected to a different file with the same name, but with the.errors appendage.

• Arguments o id – a unique clientId that is returned by the runClient()

method. It identifies the running application client’s process. o dumpFileName – the file name to which the output is redirected o destroy – a boolean flag denoting whether the process has to be

forced to terminate, or waited to finish • Return values

o return – the produced process exit code • Exceptions

o RemoteException – this exception is thrown if problems occur while stopping the application client


public int stopClient(int id, String dumpFileName, boolean destroy) throws RemoteException;

105/309


runClient(String appname, String args, Properties additionalProperties)

This method runs an application client on a different JVM, passing the user-provided arguments to the application client’s main class. The method does not wait for the process produced for the application client to finish. Waiting can be performed subsequently using the stopClient() method. Additional properties can be passed to add a classpath to the user classes or to change the initial context factory used by the application client. If these additional properties are null, this method acts like the runClient() method, without additional properties in the argument list.


of the whole application) o args – the arguments passed to the application client’s main class o additionalProperties – the additional properties passed to the

process producer • Return values

o return – a unique clientId that is used later to identify the running application client’s process when stopping or destroying the process


stopping the application client


public int runClient(String appname, String args, Properties additionalProperties) throws RemoteException;

processClient(String appname, String args, String dumpFileName, Properties additionalProperties)

This method runs an application client on a different JVM, passing the user-provided arguments to the application client’s main class. The method waits for the process to finish and then returns its exit code. The process output is redirected to a specified file and errors are redirected to a different file with the same name, but with the .errors appendage. Additional properties can be passed to add a classpath to the user classes or to change the initial context factory used by the application client. If these additional properties are null, this method acts like the runClient() method, without additional properties in the argument list.

106/309



of the whole application) o args – the arguments passed to the application client’s main class o dumpFileName – the file name to which the output is redirected o additionalProperties – the additional properties passed to the

process producer • Return values

o return – the produced process exit code • Exceptions

o RemoteException – this exception is thrown if problems occur while stopping the application client


public int processClient(String appname, String args, String dumpFileName, Properties additionalProperties) throws RemoteException; }

Example

The EAR file of this example application contains an application client and a Session EJB. The application client invokes the bean’s hello() method and then gets and outputs its answer. In this way, the application demonstrates the use of beans by the application clients and also the use of the actual application client.

The example source is available in <SAPj2eeEngine_install_dir>/docs/examples/services/appclient.

The following sequence of shell commands deploys and starts the application:

• add deploy– adds the DEPLOY group of shell commands • deploy <path to the appClientDemo.ear> - deploys the application • add appclient – adds the APPCLIENT group of shell commands • runclient AppClient null con – runs the application client and

displays its output on the console

How the Example Works

First, the application client has to obtain the client naming context:

107/309


//Set the properties required for obtaining a naming context Properties properties = new Properties(); properties.put(Context.INITIAL_CONTEXT_FACTORY, "com.inqmy.services.jndi.InitialContextFactoryImpl"); //Get a naming context try { context = new InitialContext(properties); } catch (NamingException ne) { System.out.println("Could not obtain naming : " + ne.getMessage()); return; }

If the context is obtained successfully, the system tries to lookup the bean’s home interface. Since the context is received from the application client, it has offset appclients. Therefore, the lookup must be performed using java:comp/env as prefix. The bean is then created, and its hello() method invoked. It returns a string:

try { //Create the bean AppClientHome beanHome = (AppClientHome) context.lookup("java:comp/env/ejb/AppClientHome"); AppClient bean = beanHome.create(); //Invoke method from a bean and output the result String result = bean.hello(); System.out.println("\nThe bean returned : " + result); } catch (NamingException ne) { System.out.println("Could not lookup AppClientBean : " + ne.getMessage()); } catch (Exception e) { e.printStackTrace(); }

The bean’s hello() method looks like this:

public String hello() throws RemoteException { return "Hello, this is AppClientBean !"; }

The hello() method invocation shows the relationship between the application client and the EJBean. The reference to the bean is made using the <ejb-link> tag from the application-client.xml descriptor. Therefore, it must exist in the descriptor, despite being optional in the J2EE Specification™.

108/309


DBMS Service

Overview

DBMS Service (Database Management System) is a distributed, scalable database engine. It is a core service that manages the persistent storage of SAP J2EE Engine. It provides for fail-over recovery by using replication. Clients access it indirectly using other APIs (JNDI, JDBC, JMS, JTA, JTS) and services (EJB Service, Servlet_jsp Service, and so on).

DBMS Service manages objects, and containers that group objects. Containers are distributed on multiple server nodes. When functioning as a distributed module, DBMS Service has to deal with a number of problems related to concurrency and synchronization. To avoid data loss and overall system failure in cluster environment, two types of server nodes are defined – Primary Storage Server, and Non-Primary Storage Server (Dependent Element). Primary servers store valid data, which is replicated to other server nodes that have failed, are restarted, or are additionally connected to the cluster. A SAP J2EE Engine cluster has at least one primary storage server. When another primary server joins the cluster, its data is deleted and the information of the already running primary server is replicated on the new one. A cluster with a single primary server node is not functional if the primary server fails. In addition, there are no limitations on the number of primary server nodes in cluster.

Note: Whether a server element is primary or non-primary depends on the value of DependentElement property of Cluster Manager. For more information on this property, refer to Cluster Manager section of Administration Manual.

DBMS Service enables transaction concurrency using read and write locks. These are imposed to solve problems with overwriting data, or obtaining valid data in case of simultaneous read and write operations within the database. In addition, DBMS Service offers 2PC (two-phase commit), which is a solution that provides valid data in a distributed environment. 2PC first, sends a notification that a transaction will be committed to all server nodes in the cluster, and then, commits or rollbacks the transaction. The synchronization between the server nodes when committing a distributed transaction avoids lost or overwritten data.

109/309


DBMS Service also enables you to work with virtual memory only. This option is used for SAP J2EE Engine CD installation. In this case, DBMS Service does not create files on the hard drive, but uses virtual memory files instead.

Interfaces

This service does not provide any interfaces that could be used directly by clients.

110/309


DBPool Service

Overview

DBPool Service creates and manages pools of database connections. This module is developed in accordance with JDBC 2.0 Specification.

DBPool Service is the layer between client and JDBC drivers that generate database Connection objects. The newly created Connection objects are provided to clients, and after being released by them, the connections are stored into a queue data structure to be reused. Connection pooling saves time in generating Connection objects, thereby improving overall performance.

To perform its functions, this module uses Transaction Service and Naming Service. DBPool Service connects to the database while Transaction Service manages the transactions that perform some kind of operations (read or write) in the database. DBPool Service supports distributed transactions and 2PC (two-phase commit) protocol. Naming Service is used by DBPool for binding objects in the following subcontexts – cpoolprops/ (for connection pool properties); jdbc/ (for Data Source objects that are used to retrieve Connection objects); drivers/ (for registered JDBC drivers), and cpool/ (clients cannot access this subcontext).

Typically, DBPool Service is accessed by EJB container through applications, but it can be accessed by other clients through its PoolManager interface. The functions it provides are explained below.

Interfaces

PoolManager

This is a remote interface that manages connection pools. PoolManager is the implementation of RuntimeInterface in DBPool Service; it is the service interface that is returned by ServiceReference when a lookup operation for dbpool is performed in naming.

PoolManager interface provides methods to create, delete, and manage existing pools; add and remove drivers; retrieve lists of connections currently in use, and registered drivers and pools, and so on.

111/309


public void registerUsage(String poolName) throws RemoteException

This method registers the usage of a pool with the specified poolName. It increases in line with the number of times this pool is used:

• Arguments o String poolName – the name of the pool for which usage is

registered • Exceptions

o RemoteException – denotes a communication error that occurred while performing remote operation

public void unregisterUsage(String poolName) throws RemoteException

This method reduces in line with the number of times a pool with specified poolName is used:

• Arguments o String poolName – the name of the pool for which the number of

usage sessions is reduced • Exceptions


public int getUsage(String poolName) throws RemoteException

This method returns the current number of times when usage of a pool with specified poolName is registered:

• Arguments o String poolName – the name of the pool

• Return values o An integer that specifies how many times usage of the specified

pool is registered • Exceptions


112/309


public int getOpenConnections(String poolName) throws RemoteException

This method returns the number of open connections to the database within a pool with specified poolName:


open connections is returned • Return values

o An integer that specifies the number of open connections within the pool

• Exceptions o RemoteException – denotes a communication error that occurred

while performing remote operation

public int getFreeConnections(String poolName) throws RemoteException

This method returns the number of free (reusable) database connections within a pool with specified poolName:


free connections is returned • Return values

o An integer that specifies the number of free connections within the pool



public int getAllConnections(String poolName) throws RemoteException

This method returns the number of both open and free database connections within a pool with specified poolName:


connections is returned • Return values

113/309


o An integer that specifies the number of free and used connections within the pool



public String [][] listConnections(String poolName) throws RemoteException

This method returns a list of connections and their IDs within a pool with specified poolName:

• Arguments o String poolName – the name of the connection pool

• Return values o A bi-dimensional String array that contains the IDs of the free and

the used connections in the specified pool • Exceptions


public void closeConnection (String poolName, int connID) throws RemoteException

This method closes a connection specified by ID within a pool with specified poolName:

• Arguments o String poolName – the name of the pool within which resides the

connection o int connID – the ID of the connection to be closed



public void destroyConnections(String poolName, int connID) throws RemoteException

This method permanently destroys a database connection specified by ID and residing within a pool with specified poolName:

• Arguments o String poolName – the name of the pool within which resides the

connection

114/309


o int connID – the ID of the connection to be destroyed • Exceptions


public void registerPool(String name, Properties p) throws RemoteException, SQLException

This method registers a pool with the specified name and properties, passed to it as arguments:

• Arguments o String name – the name of the pool to be registered o Properties p – the initial properties that are assigned to the pool

when it is registered • Exceptions


o SQLException – denotes an error that occurred while accessing the database

public void deletePool(String name) throws RemoteException

This method deletes a pool with the specified name:

• Arguments o String name – the name of the pool to be deleted



public void closePool(String name) throws RemoteException, SQLException

This method closes a pool with the specified name:

• Arguments o String name – the name of the pool to be closed


while performing remote operation o SQLException – denotes an error that occurred while accessing the

database

115/309


public void changePoolProperties(String name, Properties p) throws RemoteException, SQLException

This method changes the properties of a pool with the specified name, and new properties passed to it as arguments:

• Arguments o String name – the name of the pool whose properties are to be

changed o Properties p – specifies the new properties to be assigned to the

pool • Exceptions


o SQLException – denotes an error that occurred while accessing the database

public void openPool(String name) throws RemoteException, SQLException

This method opens a pool with the specified name:

• Arguments o String name – the name of the pool to be opened


while performing remote operation o SQLException – denotes an error that occurred while accessing the

database

public boolean isRunning() throws RemoteException

This method checks if PoolManager (DBPool Service) has been started:

• Return values o A boolean value (either true or false). If the return value is true,

PoolManager has been started. • Exceptions


public boolean isPoolOpen(String name) throws RemoteException

This method checks if a pool with the specified name has been opened:

116/309


• Arguments o String name – the name of the pool for which the check is

performed • Return values

o A boolean value (either true or false). If the returned value is true, the specified pool is open.



public void registerDriver(String databaseDriver, SerializableFile files[]) throws RemoteException

This method registers the JDBC driver. The driver is specified by name and an array of serializable files:

• Arguments o String databaseDriver – the name of the driver to be registered o SerializableFile files[] – driver file (ZIP, JAR, and so on). You

can specify more than one file, separated by a semicolon. • Exceptions


public void removeDriver(String databaseDriver) throws RemoteException

This method removes a registered JDBC driver. The driver is specified by name:

• Arguments o String databaseDriver – the name of the driver to be removed



public Hashtable getDrivers() throws RemoteException

This method returns a Hashtable with registered JDBC drivers:

• Return values o A Hashtable object that contains references to registered JDBC

drivers • Exceptions

117/309



public boolean checkDriver(String databaseDriver) throws RemoteException

This method checks if a JDBC driver specified by name has been registered:

• Arguments o String databaseDriver – the name of the driver to be checked

• Return values o A boolean value (either true or false). If the return value is true,

the specified driver has been registered. • Exceptions


public Hashtable getPools() throws RemoteException

This method returns a Hashtable with registered connection pools:

• Return values o A Hashtable object that contains references to registered

connection pools • Exceptions


public String testPool(String name, String sql) throws RemoteException, SQLException

This method tests if a registered pool works properly:

• Arguments o String name – the name of the tested pool o String sql – an SQL query

• Return values o A String that specifies if the pool works properly, or errors occur


while performing remote operation o SQLException – denotes an error that occurred while accessing

database

118/309


public PoolPropertyInfo[] getPropertiesInfo() throws RemoteException

This method retrieves information about pool properties:

• Return values o An array of objects that contain default values for all pool

properties. The information retrieved includes property name, value, and description.



Example

DBPool Example implements the functions of the PoolManager interface. Its source is available in the <SAPj2eeEngine_install_dir>/docs/examples/services/dbpool/db_pool directory.

The example can be started using the DbPool script file, located in the <SAPj2eeEngine_install_dir>/docs/examples/services/dbpool directory.

Note: To run DBPool example, a JDBC driver and a running database server must be available.

DbPoolExample.java

This class extends the class DbPoolExampleInterfaceImpl. It is developed in accordance with the common framework for SAP J2EE Engine Services examples.

DbPoolExample class overwrites the process() method that is defined in the ExampleInterface. The following operations are performed within the process() method:

• managerRunning() – checks if PoolManager has been started • registerAndCheckDriver() – first registers a JDBC driver, and then

checks if the driver has been registered properly • regPool() – registers a connection pool by specified driver properties • openAndCheckPool() – opens an existing pool and checks if it has been

opened

119/309


• registerAndGetUsage() – registers if the pool is being used and returns the number of times it has been used

• getConnections() – returns the number of open database connections from a particular pool

• getDBDrivers() – prints a list of registered drivers • getPoolsNames() – prints a list of registered pools • getProperties() – retrieves and prints information about all properties

– name, default value, and description • changeProperties(Properties props) – changes pool properties to the

specified values • testPool() – tests if the specified pool is working properly • unregUsage() – unregisters JDBC driver usage • closingPool() – closes the connection pool • delPool() – deletes the specified connection pool • removeDBDriver() – removes the specified JDBC driver

Note: For more details, refer to the javadoc for these methods in DbPoolExample.java.

120/309


Deploy Service

Overview

This is a core service. It manages the deployment of J2EE applications on the corresponding containers across the cluster. The service controls all actions that can be performed on containers to obtain information about deployed applications or modify them. It also keeps all deployed applications in the cluster up to date.

Interfaces

DeployService

The DeployService interface manages all deployment actions on the servers in a cluster. The container service system is used to deploy specific components. Each service can declare its own container support and types of components that can be deployed on it. The container supplies an implementation of com.inqmy.services.deploy.container.ContainerInterface and it deploys its own components using this container class. The component elements must be packed in JAR files that have at least one XML file describing the archive components. The XML file must contain a DOCTYPE element, which is one of the declared document types in the container. The Deploy Service can then recognize the container to which it should deploy the application. All actions that a container can perform are done using the DeployService. If the container name is not specified in a method, the Deploy Service looks through all services to find the right one for this component. If the container name is not specified, the action is performed on all registered container services on the specified servers or, if the servers are not specified, on all containers in all servers currently working in the cluster.

public String[] deploy(String earFile, String[] remoteSupport, Properties props) throws java.rmi.RemoteException

This method deploys all recognized components found in the archive file on the specified servers:

• Arguments o String earFile – the file that is transferred to the local machine

and which points to the EAR

121/309


o String[] remoteSupport – the remote support for these components

o Properties props – the specification used (J2EE_1_3 or J2EE_1_2); whether the root lookup is used (true or false); and the container type (A or B)

• Return values o This method returns a string array of names of the deployed

components concatenated with a dash, as well as a string representation of their type

• Exceptions o java.rmi.RemoteException – denotes that errors have occurred

while reading an archive, or that some of the components cannot be deployed successfully

public String[] update(String archiveName, Properties props) throws java.rmi.RemoteException

This method updates, adds or removes already deployed EARs:

• Arguments o String archiveName – the name of the EAR that contains the

update information o Properties props – the specification used (J2EE_1_3 or J2EE_1_2);

whether the root lookup is used (true or false); and the container type (A or B)

• Return values o This method returns null. If the application to be updated is not

deployed on the server, this method returns the same string as the deploy method.

• Exceptions o java.rmi.RemoteException – this exception is thrown when some

of the components cannot be updated, or when errors had occurred while reading the archive

public void remove(String applicationName) throws java.rmi.RemoteException

This method removes the specified application from the whole cluster:

• Arguments o String applicationName – the name of the application to be

removed • Exceptions

122/309


o java.rmi.RemoteException – thrown if some of the application components cannot be removed

public String[] listContainers(String[] serverNames) throws java.rmi.RemoteException

Lists the names of all currently working containers in the cluster where components can be deployed:

• Arguments o String[] serverNames – a list of servers whose containers are to

be listed. All containers are listed if this argument is null. • Return values

o This method returns a string array of all containers that work on any of the specified servers.

• Exceptions o java.rmi.RemoteException – thrown if an abnormal condition

occurs

public String[] listApplications(String containerName, String[] serverNames) throws java.rmi.RemoteException

This method gets the names of all deployed applications on a specified container and server. All applications on all registered containers are listed if the container name is null. All servers in the cluster are listed if the serverNames is null.

• Arguments o String containerName – the name of the container whose

applications are listed o String[] serverNames – a list of servers whose container

applications are to be listed • Return values

o This method returns a string array of all deployed applications. • Exceptions

o java.rmi.RemoteException – thrown if an abnormal condition occurs

123/309


public String[] listElements(String containerName, String applicationName, String[] serverNames) throws java.rmi.RemoteException

This method gets the names of all deployed components for a specified application in a particular container and server. If containerName is null, all components for the specific application on all registered containers are listed. If serverNames is null, the elements of all servers in the cluster are listed.

• Arguments o String containerName – the name of the container whose

components are listed o String applicationName – the name of the application to which

the listed components belong o String[] serverNames – a list of servers whose container

components are to be listed • Return values

o This method returns a string array that lists all components that belong to the application and that are deployed on the specified container that works on particular servers.

• Exceptions o java.rmi.RemoteException – thrown if an abnormal condition

occurs.

public String[] getDeclaredXMLs(String containerName) throws java.rmi.RemoteException

This method lists the names of the expected XML files with component descriptors:

• Arguments o String containerName – the name of the container whose XML

files are to be listed • Return values

o This method returns a string array that lists the XML files this container expects

• Exceptions o java.rmi.RemoteException – thrown if abnormal conditions occur

124/309


public String[] getDeclaredDocTypes(String containerName) throws java.rmi.RemoteException

This method lists the names of the first DOCTYPE XML tag found in each of the declared XML files:

• Arguments o String containerName – the name of the container whose XML

DOCTYPEs are listed • Return values

o This method returns a string array that specifies the list of XML DOCTYPEs that this container expects for its components.


public SerializableFile getClientJar(String applicationName) throws java.rmi.RemoteException

This method gets an array of JAR files that contain the required classes for the client application:

• Arguments o String applicationName – the name of the application whose

client JAR is taken • Return values

o This method returns a SerializableFile that contains the bytes of each client file with the component classes.


public String[] getSupports() throws java.rmi.RemoteException

This method lists the names of the services that can generate remote support:

• Return values o This method returns a string array of the supporting protocols for

the application (P4, RMI, IIOP, and so on). • Exceptions

o java.rmi.RemoteException – thrown if abnormal conditions occur

125/309


public void registerContainer(String containerName, ContainerInterface container) throws java.rmi.RemoteException

This method registers a new container when a service using a container is started:

• Arguments o String containerName – the name of the container that has been

registered o ContainerInterface container – the container that has been

registered • Exceptions

o java.rmi.RemoteException – denotes that abnormal conditions occurred

public void unregisterContainer(String serviceName) throws java.rmi.RemoteException

This method unregisters a container when the corresponding service is stopped

• Arguments o String serviceName – the name of the service that to stopped

• Exceptions o java.rmi.RemoteException – denotes that abnormal conditions

occurred

public void stopApplication(String applicationName) throws RemoteException

This method is active only for already deployed applications. It makes an application inaccessible from the client side. The application will not be available until its startApplication() method is activated again.


stopped • Exceptions

o RemoteException – thrown when abnormal conditions occur, or when there is a remote problem during the stopping process

126/309


public void startApplication(String applicationName) throws RemoteException

This starts an application that is already deployed but is in “Stopped” status:


started • Exceptions

o RemoteException – thrown when there are abnormal conditions, when there is a remote problem during the start process, or the specified application has not been deployed

public String getApplicationStatus(String applicationName) throws RemoteException

• Arguments o String serviceName – the name of the application whose status is

to be displayed • Return values

o This method returns a string that specifies the status of the application. The status can be STOPPED, STARTED, UPGRADING, STARTING or STOPPING.

• Exceptions o RemoteException – denotes that abnormal conditions occurred

public ExportInfo[] getCurrentStatus(String applicationName) throws RemoteException

• Arguments o String serviceName – obtains the status of the specified

application • Return values

o This method returns an array that specifies the current mode of the application (security roles, resource references, user mapping, and so on).

• Exceptions o RemoteException – denotes that abnormal conditions occurred

127/309


public void deployLibrary(String libName, String[] jars) throws RemoteException

This method deploys a library. Each library has a name-value pair specification. The name is a string identifier of the library name; the value contains a string array of the paths to all files belonging to this library.

• Arguments o String libName – the name of the library to be deployed o String[] jars – a list of all JAR files that belong to this library.

The JAR files are specified by strings representing the paths to the files.

• Exceptions o RemoteException – thrown when there are abnormal conditions, or

a problem during the deploy process

public void removeLibrary(String libName) throws RemoteException

This method removes an existing library with the specified name from the server:

• Arguments o String libName – the name of the library

• Exceptions o RemoteException – thrown when there are abnormal conditions, or

a problem during the remove process

public void updateLibrary(String libName, String[] jars) throws RemoteException

This method updates a specified library replacing its old contents with the new specified JAR files:

• Arguments o String libName – the name of the library to be updated o String[] jars – the list of the JAR files that represent the new

library content. Strings that represent the paths to the files specify the JAR files.

• Exceptions o RemoteException – denotes that a problem occurred during the

update process

128/309


public void makeReferences(String fromApplication, String[] toLibraries) throws RemoteException

This method makes references from an application to specified libraries:

• Arguments o String fromApplication – the name of the application o String[] toLibraries – the list of library names to be referenced

by this application • Exceptions

o RemoteException – denotes that problems occurred during the reference

public void removeReferences(String fromApplication, String[] toLibraries) throws RemoteException

This method removes references between an application and specified libraries:

• Arguments o String fromApplication – the name of the application o String[] toLibraries – the list of library names that are

referenced by this application • Exceptions

o RemoteException – denotes that problems occurred during the reference

public void deployLanguageLib(String appName, String[] jars) throws RemoteException

This method deploys language libraries to ensure multilingual support of the applications. The libraries can be deployed during the application deployment, or later.

• Arguments o String appName – the name of the application where libraries are

to be deployed o String[] jars – the array of library JAR names to be deployed

• Exceptions o RemoteException – denotes that problems occurred during the

reference

129/309


Example

This example implements the functions of the DeployService interface. Its source is available in the <SAPj2eeEngine_install_dir>/docs/examples/services/file_and_deploy/file_service directory.

This example is the same as the example for the File Service. It describes how the Deploy and File Services can be used to deploy an application on a distinct server remotely. The example uses an already deployed application.

Note: A detailed description of each method is available in commentary form in the example source code.

130/309


EISConnector Service

Overview

SAP J2EE Engine EISConnector Service provides easy and reliable management of the connectivity between SAP J2EE Engine and various Enterprise Information Systems (EISs). The connector architecture requires a resource adapter for every EIS. The resource adapter is a software driver, which is used by the Java application to communicate and interact with the EISs. It has to support security, transaction and connection management to plug into the application server.

EIS

EIS provides a set of services. These services are accessible as local or remote interfaces. An example of an EIS is an optional database.

Interfaces

ConnectorRuntimeInterface

This is the only interface accessible by the client. It communicates with the RADescriptor class, which is the Java representation of the ra.xml file. It defines different properties for the resource adapter instances. The functions of the ConnectorRuntimeInterface interface, and its methods, are explained below.

public Vector getInstalledAdapters() throws RemoteException

This method adds the names of the resource adapters installed in a Vector element:

• Return value o Returns a Vector element of the names of the resource adapters

installed on the server • Exceptions

o RemoteException – thrown if there are communication-related errors during a remote function call, or other error events

131/309


public void setInstalledAdapters(RADescriptor descriptor) throws RemoteException

This method installs a resource adapter with the specified RADescriptor. If changes are made to the resource adapter properties, setInstalledAdapters() saves these changes and reinstalls the existing resource adapter.

• Arguments o RADescriptor descriptor – specifies the RADescriptor of the

resource adapter instance • Exceptions


public RADescriptor getRADescriptor(String adapterName) throws RemoteException

This method gets the RADescriptor instance of the specified resource adapter:

• Arguments o String adapterName – specifies the name of the resource adapter

• Return value o This method returns the RADescriptor of the specified resource

adapter. • Exceptions


public String deploy(File archiveFile) throws RemoteException

This method deploys a resource adapter on SAP J2EE Engine:

• Arguments o File archiveFile – specifies the archive file name to be used

during the deployment process. It contains the components of the resource adapter.

• Return value o Returns the name of the already deployed resource adapter

• Exceptions o RemoteException – thrown if there are communication-related

errors during a remote function call, or other error events

132/309


public void remove(String adapterName) throws RemoteException

This method removes a specified resource adapter deployed previously on the server:

• Arguments o String adapterName – specifies the name of the adapter to be



Example

EISConnector Service example is located in <SAPj2eeEngine_install_dir>/docs/examples/services/eisconnector/eis_connector_example directory. You can start it using the EISConnectorExample script file in the same directory.

To function properly, the path to a valid resource adapter archive file must be specified.

If the resource adapter uses specific libraries, the classpath to these libraries must also be set.

A detailed description of the functions of all methods can be found within the Java source code of the example.

133/309


EJB1.1 Service

Overview

SAP J2EE Engine EJB1.1 Service manipulates and manages Enterprise JavaBeans (EJBs). It is based on JavaBeans architecture for distributed computing, and implements the EJB1.1 public release specification fully.

The basic characteristics of EJBs are:

• Each bean’s instance is created and managed by a container. • An Enterprise bean holds business logic, which is used to operate and

manage data. • Additional service information is separate from the bean’s class.

Therefore, different tools enable you to control the service information at deployment time.

The container is a vital part of the EJBs architecture. It is the environment where the bean is deployed. It also provides access to the home interfaces of beans that have already been deployed.

The home interface of the bean must be bound in the root of the naming system. The binding is performed using the bean’s name (ejb-name). Therefore, SAP J2EE Engine EJB1.1 Service does not provide support for multiple beans sharing the same name included in one or different applications. If a bean needs to be accessed by a remote client, home and remote interfaces must be added to the classpath of the client. The client’s JAR file, which can be obtained from the deploy service, must be also added to the client’s classpath.

After the deployment of the application on the server, the InitialContext with the specified username and password must be obtained. To access the bean, you must execute a lookup using the bean’s name from the naming system.

If a bean, servlet, jsp or appclient needs to perform a lookup of the home interface of another bean, a Resource reference must be defined. The code segment listed below illustrates this scenario:

Context initialContext = new InitialContext(); TestHome testHome = (TestHome)javax.rmi.PortableRemoteObject.narrow(

134/309


initialContext.lookup(“java:comp/env/ejb/test”), TestHome.class);

To look up a bean from one cluster to another, the bean to be looked up must be deployed initially. The client JAR for this bean must then be included in the EAR file of the bean that performs the lookup from the naming system.

Deployment of container-managed persistent beans is performed using an additional XML file. It defines mapping between the fields of the bean and the corresponding tables in a database (if a relational database).

Home Interface

The bean’s home interface provides methods to create, remove, and find EJB objects. The container creates the class that implements the home interface.

You can use JNDI to obtain the home interface.

Remote Interface

The EJB objects are accessible through their remote interface. It includes business methods that can be called by the client. The container creates the class that implements the remote interface.

135/309


EJB2.0 Service

Overview

SAP J2EE Engine EJB2.0 Service implements Enterprise JavaBeans™ Specification, Version 2.0, which is part of the J2EE 1.3. Specification.

EJB2.0 is only partly implemented in SAP J2EE Engine 6.20 versions. Further development is needed to fully implement the functions provided by EJB2.0 Specification.

Message-driven bean example is included in the Appendix chapter.

Interfaces

DataSourceManager Interface

DataSourceManager interface manages the lifecycle of the DataSource objects. It provides methods to create and remove DataSource instances from the cluster, along with some specific methods described below.

public void createDataSource(Properties p, SerializableFile files[]) throws RemoteException

This method creates a DataSource object with the specified properties and the driver’s archive files:

• Arguments o Properties p – specifies the relevant properties for the DataSource

object. A detailed list of the properties for the DataSource object is described later in this document.

o SerializableFile files[] – specifies an array of SerializableFile objects. It contains the archive files of the specific driver that is used to establish connection with the database.



A list of all properties of the createDataSource() method is displayed below:

136/309


• xaDataSourceName – specifies the name of the javax.sql.XADataSource object. This name is used to map this object with a corresponding javax.sql.DataSource object.

• username – specifies the username • password – specifies the user’s password • dataSourceName – specifies the name of the javax.sql.DataSource

object. This name is used to look up the object from the naming system.

If the newDriver property value is false, the following additional properties are specified:

• url – specifies the URL of the driver • driverName – specifies the classname of the driver • conns – specifies the number of the connections the driver can

maintain • isolation-level – specifies the isolation level. If not specified, the

default value of the current database is used.

If the newDriver property value is true, the following additional properties are specified:

• networkProtocol – specifies the network protocol • serverName – specifies the server name • portnumber – specifies the port • cpdsName – specifies the name of the class that implements the

javax.sql.XADataSource interface. For non-transactional connections, this property specifies the name of the class that implements the javax.sql.ConnectionPoolDataSource interface.

• objectFactory – specifies the name of the class that implements the javax.naming.spi.ObjectFactory interface. This class is used to create instances of javax.sql.XADataSource.

public void receiveFromCluster(DataSourceDescriptor dsDescriptor[], SerializableFile files[]) throws RemoteException

This method is used to create DataSource objects on every server node of the cluster. If a DataSource object is created on a particular server node, this method is invoked on other server nodes to replicate this object over the whole cluster.

• Arguments

137/309


o DataSourceDescriptor dsDescriptor[] – provides methods for setting and getting the DataSource and XADataSource names

o SerializableFile files[] – specifies an array of SerializableFile objects. It contains all archive files of the specific driver that is used to establish connection with the database.



public void removeXADS(String xadsName) throws RemoteException

This method removes a particular XADataSource object from the cluster:

• Arguments o String xadsName – specifies the XADataSource object name



public void removeDataSource(String dataSourceName, boolean deleteXADS) throws RemoteException

This method is used to remove a particular DataSource object from the cluster:

• Arguments o String dataSourceName – specifies the DataSource object name o boolean deleteXADS – specifies whether the XADataSource object,

which is mapped to the corresponding DataSource object, should be removed from the cluster. If the value is true, the XADataSource object is removed. Otherwise, it is not removed from the cluster.

JmsManager Interface

JmsManager interface is used to create and remove proxies of a particular Topic or Queue ConnectionFactory, provided by a JMS Provider. From the client point of view, ConnectionFactory is used to establish Connection with the specified provider. There is also an opportunity to create and remove Destination (Topic and Queue) with specified names. The Destination is the object that the client uses to specify the destination of the messages it is sending and the source of messages it receives.

138/309


When the proxies of the ConnectionFactory are created, they are bound in the jmsFactories context. The Topics and Queues are also bound in the jmsTopics and jmsQueues contexts respectively.

The ConnectionFactory can be used in the following cases:

• By message-driven beans – the container registers message-driven beans as listeners to the specified JMS Provider. This is performed using the <connection-factory-name> tag defined in the inqmy-ejb.xml. This tag specifies the name of the ConnectionFactory that is used by the container to register the message-driven beans. Additional information about the structure of the inqmy-ejb.xml file can be found at the end of this section.

• By all enterprise beans – all enterprise beans use the ConnectionFactory to send messages. The following code segment illustrates the process: javax.jms.QueueConnectionFactory queueConnectionFactory; javax.jms.QueueConnection queueConnection; javax.jms.Queue queue; javax.jms.QueueSession queueSession; javax.jms.Message message; ..... ..... queueConnectionFactory = (javax.jms.QueueConnectionFactory) initCtx.lookup("java:comp/env/jms/qConnFactory"); queueConnection = queueConnectionFactory.createQueueConnection(); queueSession = queueConnection.createQueueSession(true,0); queue = (javax.jms.Queue)initCtx.lookup("java:comp/env/jms/jmsQueue"); queueSender = queueSession.createSender(queue); message = queueSession.createTextMessage(); message.setText("some message");

The bean can send messages using the ConnectionFactory if a <resource-ref> tag is defined in the ejb-jar.xml file. To perform a lookup, the tag must specify /jms/qConnFactory of javax.jms.QueueConnectionFactory type (as shown in the example above). The resource is linked to an already created proxy of the ConnectionFactory. The real name of the ConnectionFactory must be specified in the inqmy-ejb.xml file. If the tag in inqmy-ejb.xml file is not specified, the resource is linked to jms/qConnFactory by default. If a ConnectionFactory with this name

139/309


was not created, an exception is thrown. The same process applies to Topics and Queues. In inqmy-ejb.xml file, a <resource-env-ref> that specifies jms/qConnFactory must be defined to perform a successful lookup from the naming system.

public void createFactory(ConnectionFactoryDescriptor connDescr) throws NamingException

This method is used to create a proxy of the ConnectionFactory of a specific JMS Provider:

• Arguments o ConnectionFactoryDescriptor connDescr – this is used when a

ConnectionFactory object is created. A detailed description is shown below.

• Exceptions o NamingException – thrown if a naming-related error occurred

A short list of the fields of ConnectionFactoryDescriptor follows:

private String factoryName = null;

This is the name of the ConnectionFactory to be created.

private boolean hasNaming = false;

The value of the boolean variable hasNaming is true if the JMS Provider provides a naming system to obtain the ConnectionFactory. Otherwise, it is set to false.

The following fields are specified if hasNaming is true:

private String linkFactoryName = null;

This is the name of the ConnectionFactory that is obtained after a lookup from the naming system is performed.

private Properties contextProperties = null;

These properties are used to create the InitialContext.

The following fields are specified if hasNaming is false. In this case, an ObjectFactory is provided to the client:

private String objectFactoryName = null;

140/309


This is the class name of the ObjectFactory.

private String className = null;

This is the class name of the object that is instantiated from ObjectFactory.

private Properties createFactoryProperties = null;

These are the properties that are passed to the ObjectFactory.

public void removeFactory(String factoryName) throws NamingException

This method removes a proxy of the ConnectionFactory with the specified name:

• Arguments o String factoryName – specifies the name of the ConnectionFactory

to be removed • Exceptions

o NamingException – thrown if a naming-related error occurred

public void createTopic(String factoryName, String topicName) throws NamingException;

This method creates a Topic with the specified name:

• Arguments o String factoryName – specifies the name of the

TopicConnectionFactory o String topicName – specifies the name of the Topic to be created


The process of creating the Topic is shown below:

TopicConnectionFactory factory = (TopicConnectionFactory)jmsFactoriesContext.lookup(factoryName); TopicConnection connection = factory.createTopicConnection(); TopicSession session = ((TopicConnection)connection).createTopicSession(false, Session.AUTO_ACKNOWLEDGE); Topic topic = session.createTopic(topicName); //System.out.println("Bind Topic : " + topic); AdminUtils.bind(jmsTopicsContext, topicName, topic, false); connection.close();

141/309


public void createQueue(String factoryName, String queueName) throws NamingException

This method creates a Queue with the specified name:

• Arguments o String factoryName – specifies the name of the

QueueConnectionFactory o String queueName – specifies the name of the Queue to be created


The process of creating a Queue is similar to the Topic process shown above.

public void removeTopic(String topicName) throws NamingException;

This method removes a Topic with the specified name:

• Arguments o String topicName – specifies the name of the Topic to be removed


public void removeQueue(String queueName) throws NamingException

This method removes a Queue with the specified name:

• Arguments o String queueName – specifies the name of the Queue to be


o NamingException – thrown if a naming-related error occurred

Description of inqmy-ejb.xml

You must use this deployment descriptor when the JAR file includes message-driven beans. It is optional for other types of EJBs.

inqmy-ejb.xml has the following format:

142/309

<!ELEMENT inqmy-ejb (description?, enterprise-beans, transaction-descriptor?,security-permission?,persistent-data-properties?)>  <!ELEMENT description (#PCDATA)>  <!ELEMENT enterprise-beans (enterprise-bean+)>  <!ELEMENT enterprise-bean (ejb-name,jndi-name,destination-name?,connection-factory-name?,properties?,container-size?,load-factor?,resource-ref*,ejb-ref*,resource-env-ref*)>  <!ELEMENT destination-name (#PCDATA)>  <!ELEMENT ejb-name (#PCDATA)> 

143/309

<!ELEMENT container-size (#PCDATA)>  <!ELEMENT load-factor (#PCDATA)>  <!ELEMENT properties (property+)>  <!ELEMENT property (property-name,property-value)>  <!ELEMENT property-name (#PCDATA)>  <!ELEMENT property-value (#PCDATA)>  <!ELEMENT resource-ref (res-name,res-link,user-name?,password?)>  <!ELEMENT res-name (#PCDATA)>  <!ELEMENT res-link (#PCDATA)>

144/309

<!ELEMENT user-name (#PCDATA)>  <!ELEMENT password (#PCDATA)>  <!ELEMENT jndi-name (#PCDATA)>  <!ELEMENT connection-factory-name (#PCDATA)>  <!ELEMENT resource-env-ref (res-env-name,jndi-name)>  <!ELEMENT res-env-name (#PCDATA)>  <!ELEMENT jndi-name (#PCDATA)> <!-- Ejb-ref element is defined in ejb-jar.xml file. It is used to specify the JNDI name of the real EJB reference.

145/309

--> <!ELEMENT ejb-ref (ejb-ref-name,ejb-ref-link)>  <!ELEMENT ejb-ref-name (#PCDATA)>  <!ELEMENT ejb-ref-link (#PCDATA)>  <!ELEMENT transaction-descriptor (isolation-level+)>  <!ELEMENT isolation-level ( method+, isolation-attribute)>  <!ELEMENT isolation-attribute (#PCDATA)>  <!ELEMENT security-permission (security-role-map+)>  <!ELEMENT security-role-map (security-role, user*, group*)>

146/309

<!ELEMENT security-role (#PCDATA)>  <!ELEMENT user (#PCDATA)>  <!ELEMENT group (#PCDATA)>  <!ELEMENT method (ejb-name, method-intf?, method-name, method-params?)>  <!ELEMENT method-intf (#PCDATA)>  <!ELEMENT method-name (#PCDATA)>  <!ELEMENT method-params (method-param*)> <!-- Method-param element specifies particular enterprise bean method parameter.

147/309

--> <!ELEMENT method-param (#PCDATA)>  <!ELEMENT persistent-data-properties (load-strategy?,properties?)>  <!ELEMENT load-strategy (#PCDATA)>

148/309


File Service

Overview

File Service is used to upload or download files on a particular SAP J2EE Engine. This service is intended to assist the Deploy Service when big EAR files must be deployed. You must upload the EAR files to the server before deployment, and to transfer the files between cluster elements during deployment.

To upload a file, you must specify the file path and the location on the server where it is to be saved. This file can be deployed remotely. The client jar files, must be specified in the application classpath that will be used by the service.

Interfaces

FileData

This interface performs the physical transfer of a file. It divides the file in parts, which size is specified by the buffer size.

public byte[] read() throws IOException

This method reads a specified file:

• Return values o Returns byte array that specifies the read part of the file

• Exceptions o IOException – thrown in case of an error

public void write(byte[] data, int off, int length) throws IOException

This method writes the data with defined beginning and length:

• Arguments o byte[] data – the byte array of data o int off – the number that specifies the position in byte[] data for

next data array to be written. o int length – the number of bytes to be written in the byte[] data

149/309



public void openRead() throws IOException

This method opens a file for reading:


public void openWrite() throws IOException

This method opens a file for writing:


public void closeRead() throws IOException

This method is invoked for closing a file after it has been opened for reading. It transfers data bytes.


public void closeWrite() throws IOException

This method is invoked for closing a file after it has been opened for writing:


public int getBufferSize()

This method gets the buffer size:

• Return values o Returns an integer that specifies the buffer size

public void setBufferSize(int size)

This method sets a new buffer size:

• Arguments

150/309


o int size – the amount of the buffer size

FileTransfer

This interface creates a logical connection between the local and the remote file. FileTransfer is the main interface that is shown after the lookup of the service.

public RemoteFile createRemoteFile(String localFile, String remoteFile) throws RemoteException

This method creates a remote file. It is recommended this method to be used instead of the next one if SAP J2EE Engine is a remote server.

• Arguments o String localFile – a string argument that specifies the name of

the local file o String remoteFile – a string argument that specifies the path and

the name of the remote file. It is recommended the file path to be relative to the server directory.

• Return values o RemoteFile – returns the remote file

• Exceptions o RemoteException – thrown when communication errors occur

during the remote call execution

public RemoteFile createRemoteFile(File localFile, File remoteFile) throws RemoteException

This method creates a remote file. An absolute file path can be used when the remote and local files are positioned on one machine.

• Arguments o File localFile – the path to the local file o File remoteFile – the path to the remote file

• Return values o RemoteFile – returns the remote file

• Exceptions o RemoteException – thrown when communication errors occur

during the remote call execution

151/309


RemoteFile

This interface synchronizes the transferred files.

public synchronized void download() throws IOException

This method synchronizes the process of file download. It downloads the remote file to the local machine.

public int getRemoteBufferSize()

This method is invoked to get the remote file buffer size:

• Return values o Returns integer number that specifies the buffer size

public RemoteFile(File local, FileData remote)

This constructor initializes a file object that specifies the remote file:

• Arguments o File local – the path to the local file o FileData remote – specifies the remote file data

public void setBufferSize(int size)

This method sets a buffer size:

public void setRemoteBufferSize(int size)

This method sets the buffer size for the remote file:

• Arguments o int size – an integer argument that specifies the size of the

remote file buffer

public synchronized void upload() throws IOException

This method synchronizes the process of file upload. It uploads the local file to the server using the name specified in the RemoteFIle constructor.

152/309


Example

To run the example, the full path to the client jar on the server must first be specified. This file can be found in <SAPj2eeEngine_install_dir>/cluster/server/services/ejb/work/applications/<application_name>/cljar<jarName> if you use the cluster version, and in <SAPj2eeEngine_install_dir>/alone/services/ejb/work/applications/<application_name>/cljar<jarName> if you use the stand-alone version. All other paths are made relative for user convenience, but they can be changed – for example, instead of ../../deploy/ear_maker/TestEAR.ear, as in the example, you can specify the full path to the ear file to be deployed. Instead of “result/FileResult.jar,” which saves the downloaded ear in the result folder in the directory from which the example is started, you can also specify the full path to another directory.

The example source is available in the <SAPj2eeEngine_install_dir>/docs/examples/services/file_and_deploy/file_service directory.

The example is started using the FileServiceExample script file, located in the <SAPj2eeEngine_install_dir>/docs/examples/services/file_and_deploy directory.

153/309


HTTP Service

Overview

HTTP service is a standard Web service that implements HTTP 1.1 protocol (specified by RFC#2616).

The HTTP protocol is a request and response protocol. A client sends a request to the server in the form of a request method, URI, and protocol version, followed by a MIME-like message containing request modifiers, client information, and possible body content over a connection with a server. The server responds with a status line, including the message’s protocol version, and a success or error code, followed by a MIME-like message containing server information, entity metainformation, and possible entity-body content.

A client may send an HTTP request for a file to the HTTP Service, which responds by sending back the file from the corresponding URL. In this way, files may be downloaded, uploaded or just viewed using the proper client application.

From the client’s point of view, the HTTP Service represents a server socket that listens for client HTTP requests. To build such requests, you can use the following standard Java classes:

• java.net.URL – represents a pointer to some kind of a resource on the World Wide Web

• java.net.HttpURLConnection – represents java.net.URLConnection with support for HTTP-specific features

• java.net.Socket – this class implements client sockets

Interfaces

HTTP Service provides a single interface to the client that can be used in runtime administration.

HttpRuntimeInterface

This interface facilitates runtime administration of the service.

154/309


public void setValue(Vector hosts)

This is used for setting addresses of the virtual hosts:

• Arguments o Vector hosts – provides new addresses of hosts

public Vector getValue()

This returns the addresses of the virtual hosts.

public ConcurrentHashMapIntObject getRootDirs()

This returns the root directories of all hosts.

public void addAlias(String alias, String warFilePath)

This adds an alias to the specified WAR file.

• Arguments o String alias – the actual name of the alias o String warFilePath – represents the path to the WAR file

public void removeAlias(String alias)

This removes an alias to a specified WAR file.

• Arguments o String alias – the name of the alias to be removed

public void clearCache()

This clears the HTTP cache.

public void registerServletAndJspContainer(ServletAndJspContainer servletAndJsp)

This registers the container to process requests for servlets or JSP files.

• Arguments o ServletAndJspContainer servletAndJsp – specifies the name of

the implementation of the interface ServletAndJspContainer to be registered

155/309


public void changeHttpRoot(String newRoot)

This sets a new root directory for the HTTP server.

• Arguments o String newRoot – specifies the name of the new directory

Example

There is nothing specific in the way HTTP Service is used by clients. It serves standard HTTP requests. For that reason, no example is presented here.

156/309


HTTP Tunneling Service

Overview

The HTTP Tunneling Service transports information encoded by the HTTP Protocol. In this way, you can open a “tunnel” through Proxy or Firewall for communication with a service that provides HTTP Tunneling. This service can be used by any other service.

HTTP Tunneling Service does not provide any interfaces that can be used remotely by the user.

Example

An example is available in the <SAPj2eeEngine_install_dir>/docs/examples/services/httptunneling directory. To run the example, you must deploy the Calc.jar file, located in the same directory. The example can be then started using the Httptunneling script file, located in the <SAPj2eeEngine_install_dir>/docs/examples/services/httptunneling directory.

157/309


IIOP Service

Overview

IIOP (Internet Inter-ORB Protocol) is the communication protocol of CORBA (Common Object Request Broker Architecture). It facilitates remote communication between CORBA objects – clients and servers. This service also enables RMI objects to use IIOP protocol and communicate with CORBA objects (however, this technology is subject to minor restrictions).

A CORBA object is an instance of a class that implements the org.omg.CORBA.Object interface. This is analogous to the RMI remote objects that implement the java.rmi.Remote interface. The implementation class of the interface of the CORBA object extends the org.omg.CORBA.portable.ObjectImpl class. This is the base class for generating stubs and for all object implementations.

Objects that communicate using RMI over IIOP extend the javax.rmi.PortableRemoteObject. They are not pure CORBA objects. However, the methods of PortableRemoteObject enable the communication over IIOP between the client and the server side object that is connected to the corresponding ORB object.

A CORBA object could be accessible for clients only if it is connected to an ORB object. The ORB object is an important component of the system. It stores the relationships between the objects that are connected to it and the key identifiers they are assigned. This feature reflects the underlying idea of obtaining access to a CORBA object by getting a reference to it. The reference is obtained by performing a lookup in the Naming Service. It is specified by the IIOP protocol and it identifies the object by host, port and object key. The object key parameter is necessary to facilitate the system operation in a cluster environment.

IIOP Service consists of three major modules: Communication Layer, Execution System, and ORB Core. Each has specific functions, thereby simplifying to some extent the complicated process of CORBA objects communication. Communication Layer provides for requests transmission from the client to the CORBA object and back. It has both dispatcher and server implementations to reflect peculiarities of this communication. Communication Layer delivers the request in the proper format to the Execution System that

158/309


connects to ORB Core. The latter module finds the object and returns the result.

When a client looks up a CORBA object, the system returns an instance of the stub of this object to the client, not the real object. The same local representation of the remote object may be further used for remote object invocation.

For such communication, IIOP protocol defines two types of subsidiary objects – stubs and ties. The stub is a class that extends javax.rmi.CORBA.Stub and implements the remote interface. A tie is a class that extends org.omg.CORBA_2_3.portableObjectImpl and implements javax.rmi.CORBA.Tie. The stub is the implementation of the interface that is passed to the client and the tie is the server-side class. Both classes facilitate the communication between the client and the server-side object.

Interfaces

This service does not provide any interfaces that could be directly used by clients.

Note: To implement RMI objects, you must follow the RMI/IIOP specification.

159/309


JavaMail Service

Overview

JavaMail Service provides clients with a set of services used to receive and send e-mails and news. These services are described in the JavaMail Design Specification 1.2.

JavaMail Service is an independent entity that does not use other modules in its work. The e-mail services realization is supported by the methods granted by the Session object. The Session object is kept in the JNDI and is described in the JavaMail Design Specification 1.2.

Client View

JavaMail Service does not provide any methods to be used by the client. The communication between a client and JavaMail Service is realized using servlets or beans (or both). During their realization, the Session object is looked up first, and the servlet or bean logic is then implemented. The JavaMail Service contains a concrete implementation of the Transport, Folder, and MimeMessage classes.

The main purpose of JavaMail Design Specification 1.2 is to provide options for sending and receiving e-mails and news. The Session object, using public methods, gives the client Transport or Folder objects (or both). The Transport object grants methods needed for sending e-mails and news. The Folder object grants a set of methods for reading e-mails and news. Such an implementation enables the client to process e-mails and news without knowing the low level commands supported by the POP3, IMAP4, SMTP, and NNTP protocols.

In the time of the Session object creation, a host name must be specified. The Transport, Folder, and Store objects are then taken. These objects inherit the host value already entered. The Transport and Store objects’ create() method is called, which attempts to connect to the specified host. The name values, which are actually the names of the SMTP, NNTP, POP3, and IMAP4 servers, are set in SAP J2EE Engine Visual Administrator and correspond to keys named: “smtp,” “nntp,” “pop3,” and “imap4.” If none of these values is specified, the default host name is “localhost.”

160/309


JMS Service

Overview

Java Message Service (JMS) provides a common way for Java programs to create, send, receive and read enterprise messaging system messages. SAP J2EE Engine provides this service strictly based on the Sun Microsystem’s Java™ Message Service Specification version 1.0.2, available at http://java.sun.com/products/jms/docs.html.

Message-driven bean example is included in the Appendix chapter.

Messaging Styles

Two messaging styles are used in JMS applications:

• Point-to-point (PTP) • Publish-and-subscribe (Pub/Sub)

The main elements of JMS Service are:

• ConnectionFactory – the client uses this object to create a Connection • Connection – an active connection to a JMS provider • Destination – encapsulates the identity of a message destination • Session – a single-threaded context for sending and receiving

messages • MessageProducer – an object created by a Session that is used to send

messages to a specified destination • MessageConsumer – an object created by a Session that is used to

receive messages sent to a destination

JMS Application

A JMS application consists of one or more JMS clients that exchange messages. The application may also include non-JMS clients. These clients use the JMS provider’s native API instead of JMS.

161/309


Messaging Styles

JMS provides the following messaging styles:

• Text message • Stream message • Object message • Bytes message • Map message

An example on using different messages styles is available in the <SAPj2eeEngine_install_dir>/docs/examples/services/jms/messages_example directory. The example can be started using the MessagesExample script file, located in the <SAPj2eeEngine_install_dir>/docs/examples/services/jms directory.

Message Selector

The JMS Service enables you to choose the contents of the messages it receives. This feature is provided by the MessageSelector. Its syntax can be found in the JMS™ Specification. An example on using JMS Message Selector is available in <SAPj2eeEngine_install_dir>/docs/examples/services/jms/message_selector_example. To run the example, start the script file named MessageSelector_sender first, then MessageSelector_receiver, located in the <SAPj2eeEngine_install_dir>/docs/examples/services/jms directory.

Developing a JMS Client

A typical JMS client executes the following JMS setup procedure:

• Uses JNDI to find a ConnectionFactory object // initialize JMS properties Properties properties = new Properties(); properties.put(Context.INITIAL_CONTEXT_FACTORY, "com.inqmy.services.jndi.InitialContextFactoryImpl"); properties.put(Context.SECURITY_PRINCIPAL, "Administrator"); properties.put(Context.SECURITY_CREDENTIALS, ""); // initalizing the InitalContext with the selected properties InitialContext context = new InitialContext(properties);

162/309


// looking up the TopicConnectionFactory topicConnectionFactory = (TopicConnectionFactory) context. lookup("TopicConnectionFactory");

• Uses the ConnectionFactory to create a JMS Connection

// topic connection topicConnection = topicConnectionFactory.CreateTopicConnection(); //start the connection topicConnection.start();

• Uses the Connection to create one or more JMS Sessions

//create TopicSession topicSession = topicConnection.createTopicSession(); // create topic topic = topicSession.createTopic(String topicName);

• Uses a Session and the Destinations to o create the MessageProducer

// create message producer topicPublisher = topicSession.createTopicPublisher(topic);

o create the MessageConsumer // create topic subscriber topicSubscriber = topicSession.createSubscriber(topic); // create message listener topicSubscriber.setMessageListener(this);

• Tells the Connection to o start message delivery

// receive message textMessage = (TextMessage) topicSubscriber.receive();

o start message sending // first create a message to publish TextMessage textMessage = new TextMessage(“Some Text Message”); // sending message to the topic topicPublisher = session.createTopicPublisher(String topicName);

163/309


// publish the message topicPublisher.publish(textMessage);

Interfaces

QueueConnectionFactory

A client uses a QueueConnectionFactory to create QueueConnections with a JMS PTP provider.

public javax.jms.QueueConnection createQueueConnection() throws javax.jms.JMSException

This creates a queue connection with default user identity:

• Returns o a newly created queue connection

• Exceptions o JMSException – if JMS Provider fails to create Queue Connection

because of an internal error o JMSSecurityException – if client authentication fails because of an

invalid user name or password

public javax.jms.QueueConnection createQueueConnection (String userName, String password) throws javax.jms.JMSException

This creates a queue connection with specified user identity:

• Arguments o userName – the caller’s user name o password – the caller’s password

• Returns o A newly created queue connection

• Exceptions o JMSException – if JMS Provider fails to create Queue Connection



For more information on how to use this factory, refer to the <SAPj2eeEngine_install_dir>/docs/examples/services/jms/queue_example directory. The example can be started using the QueueExample script file,

164/309


located in the <SAPj2eeEngine_install_dir>/docs/examples/services/jms directory.

TopicConnectionFactory

The client uses a TopicConnectionFactory to create TopicConnections with a JMS Pub/Sub provider.

public javax.jms.TopicConnection createTopicConnection() throws javax.jms.JMSException

This creates a topic connection with default user identity:

• Returns o A newly created topic connection

• Exceptions o JMSException – if the JMS Provider fails to create a Topic

Connection because of an internal error o JMSSecurityException – if client authentication fails because of an


public javax.jms.TopicConnection createTopicConnection (String userName, String password) throws javax.jms.JMSException

This creates a topic connection with specified user identity:


• Returns o A newly created topic connection

• Exceptions o JMSException – if the JMS Provider fails to create a Topic



For more information on how to use this factory, refer to the <SAPj2eeEngine_install_dir>/docs/examples/services/jms/topic_example directory. The example can be started using the TopicExample script file, located in the <SAPj2eeEngine_install_dir>/docs/examples/services/jms directory.

165/309


XAQueueConnectionFactory

An XAQueueConnectionFactory provides the same create options as a QueueConnectionFactory.

public javax.jms.XAQueueConnection createXAQueueConnection() throws JMSException

This creates an XA queue connection with default user identity. The connection is created in stopped mode. No messages are delivered until the Connection.start() method is called explicitly.

• Returns o a newly created XA queue connection

• Exceptions o JMSException – if the JMS Provider fails to create XA queue



public javax.jms.XAQueueConnection createXAQueueConnection(String userName, String password) throws JMSException

This creates an XA queue connection with specific user identity. The connection is created in stopped mode. No messages are delivered until the Connection.start() method is called explicitly.


• Returns o a newly created XA queue connection

• Exceptions o JMSException – if the JMS Provider fails to create XA queue



XATopicConnectionFactory

An XATopicConnectionFactory provides the same create options as TopicConnectionFactory.

166/309


public javax.jms.XATopicConnection createXATopicConnection() throws JMSException

This creates an XA topic connection with default user identity. The connection is created in stopped mode. No messages are delivered until the Connection.start() method is called explicitly.

• Returns o A newly created XA topic connection

• Exceptions o JMSException – if the JMS Provider fails to create XA topic



public javax.jms.XATopicConnection createXATopicConnection (String userName, String password) throws JMSException

This creates an XA topic connection with specified user identity. The connection is created in stopped mode. No messages are delivered until the Connection.start() method is called explicitly.


• Returns o A newly created XA topic connection

• Exceptions o JMSException – if JMS Provider fails to create XA topic connection



Example

This example introduces the JMS Service functions. It simulates sending and receiving messages using TopicConnection and consists of three classes: Sending, Receiving and Start. The Sending class provides methods for sending messages to a specified Topic instance. The Receiving class receives these messages by subscribing to the Topic, as created by the sender of the messages. Start runs the other two classes as separate threads.

167/309


The Sending.java and Receiving.java files described in this example are located in the <SAPj2eeEngine_install_dir>/docs/examples/services/jms/send_and_receive directory. The example can be started using the SendAndReceive script file, located in the <SAPj2eeEngine_install_dir>/docs/examples/services/jms directory.

Sending Class

Looks up the TopicConnectionFactory:

topicConnectionFactory = (TopicConnectionFactory) init();

Creates topic connection:

topicConnection = topicConnectionFactory.createTopicConnection();

Starts the topic connection:

topicConnection.start();

Creates TopicSession:

topicSession = topicConnection.createTopicSession(false, 1);

Creates the specified topic:

topic = topicSession.createTopic("Example");

Creates a publisher to the topic:

topicPublisher = topicSession.createPublisher(topic);

Creates a text message and sets its contents:

textMessage = topicSession.createTextMessage(); textMessage.setText(testString + (++count));

Publishes the message:

topicPublisher.publish(textMessage);

Receiving Class

Looks up the TopicConnectionFactory:

168/309


topicConnectionFactory = (TopicConnectionFactory) init();

Creates a topic connection:

topicConnection = topicConnectionFactory.createTopicConnection();

Starts the connection:

topicConnection.start();

Creates a TopicSession:

topicSession = topicConnection.createTopicSession(false, 1);

Creates a topic:

topic = topicSession.createTopic("Example");

Creates a subscriber:

topicSubscriber = topicSession.createSubscriber(topic);

Creates a message listener:

topicSubscriber.setMessageListener(this);

Receives a message:

textMessage = (TextMessage) topicSubscriber.receive();

Gets the message contents:

textMessage.getText();

169/309


Keystore Service

Overview

The Keystore Service holds keys and certificates. The service represents an implementation of java.security.KeyStoreSpi. The certificates are used for the communications of the Security Socket Layer (SSL) Service, providing stronger file security. There are two providers for the service:

• In-Q-My Techonologies o Example –

KeyStore.getInstance(“EBSDKS”)

• Institute for Applied Information Processing and Communications Graz University of Technology (IAIK) To use the service, you need the iaik_jce.jar located in <SAPj2eeEngine_install_dir>/cluster/server/additional-lib/ or <SAPj2eeEngine_install_dir>/alone/additional-lib/. This JAR must be obtained by the SAP J2EE provider or can be downloaded from http://jcewww.iaik.at/download/evaluation/index.php.

The service cannot be used remotely. For information on using this service, refer to the Administration Manual.

Interfaces

This service does not provide interfaces that can be directly used by clients.

170/309


Log Service

Overview

Log Service is a system that allows various SAP J2EE Engine components to log significant information that is related to their operations. This information is very useful in many cases, for example, when you try to figure out the user that caused an error in an application, to locate precisely what has gone wrong with your application and so on. Log Service provides developers with APIs that allows them develop applications that make a full use of the functions of the log system.

Log Service defines 9 types of log messages. Each type is denoted by a number between 0 and 8:

• 0-EMERGENCY – system is unusable • 1-ALERT – immediate action must be taken • 2-CRITICAL – critical conditions • 3-ERROR – error conditions • 4-WARNING – warning conditions • 5-NOTICE – normal but significant events for the system • 6-INFO – information • 7-TRACE – events that occur as a result of application methods

execution • 8-DEBUG – debug-level messages

Interfaces

LogViewerInterface is an interface that provides methods used for retrieving logs of a service, a manager, or a whole cluster node. In addition to this interface, the LogObject class is also described in order to make you familiar with the methods used for getting various types of information about a single log.

LogViewerInterface

public long[] getAllDestinations()

Returns an array of all destination IDs. A destination may be a single service, a single manager or a whole cluster node.

171/309


public Properties[] getDestinationLogs(long destID)

Returns the logs of the specified destination.

• Arguments o long destID – the ID of the destination, for which are retrieved

public Vector getNextServiceLogs(byte logType, String serviceName, int count)

Returns a Vector with the specified number of logs. These logs are logs of a particular service and are of type specified by the logType parameter.

• Arguments o byte logType – the type of the log messages to be retrieved o String serviceName – the name of the service that has logged the

message o int count – the number of the log messages that are retrieved

public Vector getNewServiceLogs(byte logType, String serviceName)

Returns a Vector with retrieved logs. These logs are logs of a particular service and are of type specified by the logType parameter.

• Arguments o byte logType – the type of the log messages to be retrieved o String serviceName – the name of the service that has logged the

message

public Vector getNextManagerLogs(byte logType, String managerName, int count)

Returns a Vector with the specified number of logs. These logs are logs of a particular manager and are of type specified by the logType parameter.

• Arguments o byte logType – the type of the log messages to be retrieved o String managerName - the name of the manager that has logged

the message o int count – the number of the log messages that are retrieved

172/309


public Vector getNewManagerLogs(byte logType, String managerName)

Returns a Vector with retrieved logs. These logs are logs of a particular manager and are of type specified by the logType parameter.

• Arguments o byte logType – the type of the log messages to be retrieved o String managerName - the name of the manager that has logged

the message

public Vector getNextServicesLogs(byte logType, int count)

Returns a Vector with the specified number of logs. These logs are the logs of all services and are of type specified by the logType parameter.

• Arguments o byte logType – the type of the log messages to be retrieved o int count – the number of the log messages that are retrieved

public Vector getNewServicesLogs(byte logType)

Returns a Vector with retrieved logs. These logs are the logs of all services and are of type specified by the logType parameter.

• Arguments o byte logType – the type of the log messages to be retrieved

public Vector getNextManagersLogs(byte logType, int count)

Returns a Vector with the specified number of logs. These logs are the logs of all managers and are of type specified by the logType parameter.


public Vector getNewManagersLogs(byte logType)

Returns a Vector with retrieved logs. These logs are the logs of all managers and are of type specified by the logType parameter.


173/309


public Vector getNextClusterLogs(byte logType, int count)

Returns a Vector with the specified number of logs. These logs are the logs of a whole cluster node (all services and managers of that cluster node) and are of type specified by the logType parameter.


public Vector getNewClusterLogs(byte logType)

Returns a Vector with retrieved logs. These logs are the logs of a whole cluster node (all services and managers of that cluster node) and are of type specified by the logType parameter.


public void free()

This method releases all file references and pointers.

public void storeInfos(String time)

This method stores information about log messages and the files they are saved to in a temporary hashtable.

• Arguments o String time – the time when this information is stored

public void restoreInfos()

This method restores the information stored in the temporary hashtable by the storeInfos(String time) method

LogObject

public void setFromFile(String file)

Sets the source file for the LogObject.

• Arguments o String file – the name of the source file

174/309


public String getFromFile()

Returns the name of the source file for the LogObject.

public String getEncoding()

Returns the encoding of the source file for the LogObject.

public String getDate()

Returns the date on which the message is logged.

public String getTime()

Returns the time when the message is logged.

public String getType()

Returns the type of the log message.

public String getUser()

Returns the user who took the action that caused logging the message.

public String getClientIp()

Returns the IP of the machine of the above-mentioned user.

public String getTIME()

Returns the time when the log is created. Time denotes both the date and the daytime when it is created.

public String getCaller()

Returns name of the service or manager that logged the message.

public String getMessage()

Returns the actual log message.

public int getCluster()

Returns the cluster element on which the message is logged.

175/309


Naming Service

Overview

Naming Service is developed in accordance with the JNDI 1.2 Specification to meet the naming system requirements of Java 2 Enterprise Edition (J2EE). This service provides functions based on the JNDI 1.2 Specification as well as some additional features related to its work in cluster.

SAP J2EE Engine Naming Service provides a way by which names are associated with objects, and objects are found based on their names. The service performs binding, rebinding, and unbinding operations.

SAP J2EE Engine Naming system is a connected set of contexts of the same type, and it performs naming-related operations. The Naming Service is accessed using its own interface. The service’s context is a set of name-to-object bindings. Every context has an associated naming convention. The context provides a lookup (resolution) operation that returns the object and may provide operations such as those for binding names, unbinding names, and listing bound names. A name in one context object can be bound to another context object, called a subcontext, which has the same naming convention.

With the Naming Service, you can look up an object in the naming system by supplying it the name of the object (as a String). The naming system determines the syntax that the name must follow. The service associates names with objects and also allows such objects to have attributes. Thus, you not only can look up an object by its name, but also get the object’s attributes or search for the object based on its attributes. When you search, you can supply not a name but a query consisting of a logical expression in which you specify the attributes that the object or objects must have. The Service returns the objects that satisfy the search filter.

A link reference is a symbolic link that can span multiple naming systems. The Naming Service link references are used by the J2EE components especially to ensure the EJBeans’ security in combination with the offset contexts (a context that does not start from the naming root directory).

SAP J2EE Engine Naming Service specific features:

176/309


• Information collection – the Naming Service stores the data using the DBMS Service

• Tree structure – naming contexts and objects are arranged in a hierarchy

• Security – the SAP J2EE Engine Security Service uses the Naming Service for ensuring maximum server security

• The naming tree can be accessed from the whole cluster. This is because the DBMS Service is used to replicate the data.

• SAP J2EE Engine service’s interfaces and J2EE Components (EJBeans for example) can be obtained from the Naming Service.

Interfaces


For information on how to use Naming Service functions, refer to Lookup Resources Over the JNDI in Developers Tasks section of this manual.

177/309


P4 Service

Overview

P4 Service is based on the RMI_P4 object-oriented protocol for remote object communication specified by SAP J2EE Engine. The functions of this protocol are similar to that of the RMI (Remote Method Invocation) defined by Java™ 2 SDK, Standard Edition.

This service addresses the issues of distributed systems that require computations running in different Java Virtual Machines to be able to communicate. This is performed by employing the mechanism of communication using remote objects proxies. However, an additional object is used to locate the remote object and to enable invocation of a method on it. This object is called P4ObjectBroker and it is an essential part of this module. The RMI_P4 protocol provides solutions to the following critical issues:

• Locating and identifying the remote object • Transmitting of the parameters of the method that is invoked remotely

– even so another remote object may be passed as such a parameter • Identifying the method that is invoked on the remote object • Executing this method • Returning the result of the method execution or the exception, if such

occurs

The following description of the basic interactions of components with respect to the way the service solves these problems explains the main concepts of this module.

This service is operating at a lower level of the system and enables the remote communication between objects using the RMI_P4 protocol. This is made possible by defining a reference to each remote object. The reference identifies uniquely the association of the remote object with a particular P4ObjectBroker object, as well as the exact location of that P4ObjectBroker.

From a client’s point of view, a reference to the remote object should be obtained to get an instance of the object. The Naming Service of SAP J2EE Engine deals with obtaining the reference, not the P4 Service. When the reference is available, P4ObjectBroker delivers a local instance of the remote object to the client, and provides the connection between the local instance

178/309


and the real implementation of it. The loading of the instance of the remote object is handled by the broker object.

RMI_P4 is an object-oriented protocol that provides for remote transmission of objects between different JVMs. Two types of remote objects can be distinguished, considering the way the objects are transmitted:

• Objects transmitted by reference • Objects transmitted by value

A specific feature of the objects transmitted by value is that a local implementation is loaded on the client JVM. This implementation has no connection with the real object implementation. P4 Service uses the standard Java Object Serialization mechanism for transmission of this type of remote objects.

Objects transmitted by reference have the following characteristics:

• Extend the class com.inqmy.services.rmi_p4.P4RemoteObject • Implement interface that extends java.rmi.Remote • Have association with a P4ObjectBroker

The idea is to transmit only the reference to the remote object, not the actual object. Apart from the case of the objects transmitted by value, the reference that is received by the client JVM remains connected to the real object implementation. To facilitate this permanent connection between the “client part” and the “server part” of the remote object, there are two implementations of the P4ObjectBroker – a client side and a server side. The client broker receives the request for the method of the remote object that is called on the local Stub class and connects to the server-side broker object. The latter forwards the request to a Dispatch object to send the request to the proper Skeleton class for the remote object. The Skeleton receives the request, retrieves the parameters of the method called from the stream, and interacts with the real object to perform the real method execution.

Interfaces

This service does not provide interfaces to be used by the client. The only way a client can interfere with the system is by using the P4ObjectBroker abstract class.

From the client perspective, the P4ObjectBroker is a subsystem within the P4 Service that initialises the whole system. It is initialised by the client and

179/309


receives some particular parameters that refer to the way the other components of the system are started.

A few of the methods of P4ObjectBroker class are described here. These are the methods that can be used by the client to get the corresponding broker object. The rest of the methods of the class are of no interest to the developer because they refer to the functions of the broker object described in the previous section. They perform operations at a lower level that are not visible to the client.

P4ObjectBroker

Clients can use the following methods:

public static P4ObjectBroker init(Properties _prop)

This is used to initialize the P4ObjectBroker object. It sets some properties for the object that are given as arguments.

• Arguments o Properties _prop – this method takes some properties as

argument. The properties refer to the call timeout and the type of the transport protocol to be used (such as HTTPTunneling, SSL, and so on)

public static synchronized P4ObjectBroker init()

This initializes the P4ObjectBroker object. It checks if the object is already instantiated and if so returns the same object; otherwise, it creates an instance of it. It is called by the previous method.

• Exceptions o P4RuntimeException – thrown when the P4ObjectBroker object

cannot be initialized

public Object narrow(Object info, Class stubClass)

This returns the stub of a particular object.

• Arguments o Object info – an object that contains information about the

remote object to be accessed o Class stubClass – specifies the class over which the stub is

generated

180/309


public Object narrow(Object info, Class stubClass, String _connectionType)

This performs the same operation as the previous item. It specifies the type of connection that is going to be opened.

• Arguments o Object info – an object that contains information about the

remote object to be accessed o Class stubClass – specifies the class over which the stub is

generated o String _connectionType – specifies the type of the connection

through which the communication is completed (HTTP, SSL, and so on)

• Exceptions o ClassNotFoundException – thrown if the corresponding class

cannot be found

Example

An example is located in the following directory: <SAPj2eeEngine_install_dir>/docs/examples/com/inqmy/services/rmi_p4/p4_example.

P4Example

The following fragment of an example presents the way a client can initialize the broker object and use the P4 Service for remote call to a method of Security Service of SAP J2EE Engine:

... P4ObjectBroker broker = P4ObjectBroker.init(); RemoteServiceReference remoteObject = (RemoteServiceReference)broker.narrow(ctx.lookup("security"), RemoteServiceReference.class); System.out.println("Ok remoteObject :" + remoteObject); RemoteSecurity security = (RemoteSecurity)remoteObject.getServiceInterface(); ...

Here, two of the methods of P4ObjectBroker are used. First, the P4ObjectBroker.init() initializes the corresponding broker object (if one does not exist) or gets the broker object running in this JVM. The narrow(..) method is then used to return the stub representation of the

181/309


RemoteServiceReference interface by the information received from the lookup of the Security Service performed in the naming. Actual access to the remote interface of the service is gained using the getServiceInterface() method.

182/309


RFC Engine Service

Overview

The RFC Engine Service integrates with the SAP R/3 System. It supplies interfaces for Remote Function Calls from JCO R/3 to Stateless Session EJBeans deployed on SAP J2EE Engine. In this way, results obtained from processing the EJBeans’ methods can be used within the R/3 System.

RFC Engine Service monitors for R/3 calls using an extended JCO.Server class with handleRequest() method overridden. JCO.Function is passed through this handleRequest() method, its name is taken and a stateless session bean with that name is created. Its JCO.Function processFunction(JCO.Function)

method is then invoked. The changed data is written into the JCO.Function, which is initially passed to the handleRequest(JCO.Function) method. The result is returned to the caller.

By completing these steps, an R/3 user can invoke a JCO metastructured function implemented in a stateless session bean deployed on servers that are accessible through a certain dispatcher.

At present, RFC Engine Service can be controlled using the Visual Administrator, or its runtime interface. Both methods provide a way of working with connections to R/3 Systems – starting, stopping and changing their properties.

Interfaces

This service is used only by the SAP R/3 System. It is not used by other SAP J2EE Engine services and does not provide interfaces that can be used directly by clients.

183/309


Security Service

Overview

Security Service provides the SAP J2EE Engine security. Basically, the Security Service consists of RemoteSecurity interface and the following main modules:

• RemoteSecurity interface • User Manager • Resource Manager • Protection Domain Manager • JAAS • Login System • SAP Integration Manager

Interfaces

RemoteSecurity

RemoteSecurity interface accesses the remote parts of Security Service.

The RemoteSecurity methods are:

public CryptographyRuntimeInterface getCryptographyManager() throws java.rmi.RemoteException

• Return values o An interface to the crypt module

• Exceptions o java.rmi.RemoteException

public RemoteLogin getRemoteLoginManager() throws java.rmi.RemoteException

• Return values o An interface to the login module


184/309


public RemoteProtectionDomainManager getRemoteProtectionDomainManager() throws java.rmi.RemoteException

• Return values o An interface to the protection domain module


public RemoteResourceManager getRemoteResourceManager() throws java.rmi.RemoteException

• Return values o An interface to the resource managing module


public RemoteUserManager getRemoteUserManager() throws java.rmi.RemoteException

This gets the remote user manager.

• Return values o An interface to the user managing module


public RemoteJaasConfigurator getRemoteJaasConfigurator() throws java.rmi.RemoteException

This gets the remote JAAS module:

• Return values o An interface to the JAAS managing module


public RemoteConnectorManager getRemoteConnectorManager() throws java.rmi.RemoteException

This gets an instance of the interface managing the Connector module.

• Return values o An interface to the Connector module

185/309



public RemoteSapIntegrationManager getRemoteSapIntegrationManager() throws java.rmi.RemoteException

This gets the remote integration manager of ABAP and Java security services.

• Return values o An interface to the remote integration manager of ABAP and Java

security services. • Exceptions

o java.rmi.RemoteException

For more information on how to use the RemoteSecurity interface, refer to <SAPj2eeEngine_install_dir>/docs/examples/services/security/remote_security. The example can be started using the RemoteSecurityExample script file, located in the <SAPj2eeEngine_install_dir>/docs/examples/services/security directory.

User Manager

User Manager maintains users that are registered within the cluster. They are visible from all application containers. User Manager defines:

• Users – humans or services that require access to the server’s security-sensitive resources. Access can be granted or denied only by the administrator of the server (“Administrator”). The administrator has full rights to administrate the system resources, to create, remove, grant or deny access to the users.

• Groups – sets of users with common permissions for easier administration. By default, the groups on SAP J2EE Engine are o “root” – the main root of all users and groups o “administrators” – the group of users with administrative rights. All

users who must have administration privilegies should be created in this group. This provides full rights to the user to administer the system and all other users, including other administrators. Default users in this group are “Administrator” (with empty string as default password) and “System.” You do not have to create an administrator of the server in this group. Administrative rights can be granted to any user, no matter where the user was created.

186/309


o “guests” – contains a default user “Guest” with default password “guest”

o “external” – contains users using the JAAS protocol to log in to the server

Each user can be a member of one or more groups. When a new group is created, users can be added to it. You can remove only empty groups (without any users or subgroups). Giving permissions to a particular group grants all users in it the same rights. The default users and groups cannot be removed.

public char[] changePassword(String name, char[] password) throws SecurityException

This changes the password of the specified user:

• Arguments o name – the name of the user o password – the user password. If there is no such user, it is

ignored. If such a user exists and no password is specified, a random password is generated and returned.

• Return values o Random password for the specified user

• Exceptions o SecurityException

public char[] changePassword(char[] password) throws SecurityException

This changes the password of the current user:

• Arguments o password – new password for the user

• Return values o Random password for the current user


public char[] createUser(boolean user, String name, char[] password, String[] parentGroup) throws SecurityException

This adds a new user or group with the specified name (and password for the users):

187/309


• Arguments o user – true for users and false for groups. Some implementations

may ignore this parameter if they do not maintain groups and users.

o name – name of the user o password – the user password. If there is no such user name, it is

ignored. If it is true and no password is specified, a random password is generated and returned.

o parents – a parent group of the user or group • Return values

o Randomly generated password • Exceptions

o SecurityException

public void forceToChangePassword(String name, long time) throws SecurityException

This forces a user to change their password after a specified interval of time:

• Arguments o name – name of the user o time – the time in milliseconds after which the user is forced to

change the password • Exceptions

o SecurityException – thrown if the caller is not granted permission to force password changes, or if no such user exists

public PasswordFilter getPasswordFilter()

This gets the attributes of an allowed password:

• Return values o Randomly generated password

public int getUserId (String name, boolean user) throws SecurityException

This gets the identifier of the specified user:

• Arguments o name – name of the user o user – if it is false, the first parameter is a group name. If it is

true, the specified name is the user’s name. • Return values

188/309


o Randomly generated password • Exceptions

o SecurityException

public RemoteUserInfo getUserInfo(String name, boolean user) throws SecurityException

This gets information about the specified user. If no user is specified, information about the root user is returned.

• Arguments o name – name of the user o user – true for users and false for groups

• Return values o UserNode object representing the user or the group


public RemoteUserInfo getUserInfo(int user) throws SecurityException

This gets information about the specified user. If no user is specified, information about the root user is returned.

• Arguments o user – user identifier or a group


• Exceptions o SecurityException – thrown if the caller has no permission

granted

public void groupUser(boolean user, String name, String parent) throws SecurityException

This adds a user or a group to a parent group. Each user or group can be added to more than one group.



o name – the name of the user or the group o parent – the new parent group of the user or the group

189/309



• Exceptions o SecurityException – thrown if the caller is not granted permission

to group users, or if such user or group does not exist

public void removeUser(String name, boolean user) throws SecurityException

This removes an existing user or group by specifying its name:

• Arguments o name – the name of the user or the group o user – true for users and false for groups


to remove users, or no user with such name exists

public void setEnabled(String name, boolean user, boolean enabled) throws SecurityException

This allows or denies access to a specified user:

• Arguments o name – the name of the user or the group o user – true for users and false for groups o enabled – true to enable and false to disable


to enable or disable users, or no user with such name exists

public void setPasswordFilter(PasswordFilter filter) throws SecurityException

This changes the password filter:

• Arguments o filter – the password filter

• Exceptions o SecurityException – thrown if a password filter cannot be

changed

190/309


public void ungroupUser(boolean user, String name, String parent) throws SecurityException

This removes a user or a group from a parent group:



o name – the name of the user or group o parent – the parent group of the user or the group


to ungroup users, or if such user or group does not exist

public String[] users(boolean user) throws SecurityException

This gets the names of all registered users when the parameter is true, and the names of all registered groups when the parameter is false:



• Return values o Enumeration of user or group names


public Object verify(String name, char[] password) throws SecurityException

This checks whether the user specified by its name and password is registered. If such user exists, the method returns an implementation-dependent value. This method is used by services that manage their own users and groups. Some services may throw a SecurityException in an attempt to verify the password of a user registered by another service.

• Arguments o name – the name of the user o password – the password of the specified user

• Return values o An implementation-specific value

191/309


• Exceptions o SecurityException – thrown if no such user is registered

For more information on how to use this manager, refer to <SAPj2eeEngine_install_dir>/docs/examples/services/security/login. The example can be started using the LoginExample script file, located in the <SAPj2eeEngine_install_dir>/docs /examples/services/security directory.

ResourceManager

The basic function of Resource Manager is to handle and manage resources. A resource is an abstract object. For example, it may represent an EJB or a file. A single resource can have multiple instances. For each of these instances, different actions can be defined.

public void checkPermission(int actionId, int resourceId, int instanceId) throws SecurityException

The resource manager checks the rights of the user currently logged onto the specified resource. If a user that is not granted access to the specified resource attempts to manipulate the resource, a Security Exception is thrown.

• Arguments o actionId – action identifier as registered within the resource

context o resourceId – resource identifier as registered within the resource

context o instanceId – the instance identifiers registered within the resource

context • Exceptions

o SecurityException – thrown if the caller is denied access to the instance

public int createResource(String alias, Guard guard) throws SecurityException

This creates a resource by specifying its name and guard. The names of the resources are unique.

• Arguments o alias – the alias of the resource

192/309


o guard – the same guard should be provided for each further modification of the resource

• Return values o The unique identifier of the newly created resource

• Exceptions o SecurityException – thrown if the caller is not allowed to create

resources

public void destroyResource(int resourceId, Guard guard) throws SecurityException

This destroys the resource specified by its identifier:

• Arguments o resourceId – resource identifier o guard – the same guard should be provided when creating the

resource • Exceptions

o SecurityException – thrown if the caller is not allowed to destroy this resource

public void destroyResource(String alias, Guard guard) throws SecurityException

This destroys the resource specified by its alias:

• Arguments o alias – the name of the resource o guard – the same guard should be provided when creating the

resource • Exceptions

o SecurityException – thrown if the caller is not allowed to destroy this resource

public java.security.Permission getPermission(int actionId, int resourceId, int instanceId) throws SecurityException

This gets an instance of java.security.Permission used for authorization to access the specified instance through the specified action.

• Arguments o actionId – action identifier o resourceId – resource identifier o instanceId – instance identifier

193/309


• Return values o java.security.Permission instance

• Exceptions o SecurityException – thrown if the caller is denied access

public String getResourceAlias(int resourceId) throws SecurityException

This gets the alias of the resource specified by its resource ID.

• Arguments o resourceId – resource identifier

• Return values o The name of the resource


public RemoteResourceHandle getResourceHandle(String alias) throws SecurityException, java.rmi.RemoteException

This gets an instance of the ResourceHandle interface. It enables you to manipulate actions and instances on the specified resource.

• Arguments o alias – the name of the resource for which a handle is received

• Return values o Instance of the ResourceHandle interface

• Exceptions o SecurityException – thrown if the caller is denied access o RemoteException

public RemoteResourceHandle getResourceHandle(int resourceId) throws SecurityException, java.rmi.RemoteException

This receives an instance of the ResourceHandle interface. It enables you to manipulate actions and instances of the specified resource.

• Arguments o resourceId – resource identifier

• Return values o Instance of the ResourceHandle interface

• Exceptions o SecurityException – thrown if the caller is denied access o java.rmi.RemoteException

194/309


public int[] getResourceIds() throws SecurityException

This gets the identifiers of all resources:

• Return values o Enumeration of resource identifiers


public void renameResource(String alias, String newAlias, Guard guard) throws SecurityException

This renames a resource by using its name:

• Arguments o alias – the name of the resource o newAlias – the new name of the resource o guard – the guard provided at the creation of the resource


public void renameResource(int resourceId, String newAlias, Guard guard) throws SecurityException

This renames a resource by using its identifier:

• Arguments o resourceId – resource identifier o newAlias – the new name of the resource o guard – the guard provided at the creation of the resource


For more information on how to use this manager, refer to <SAPj2eeEngine_install_dir>/docs/examples/services/security/resource_manager.

RemoteResourceHandle

Using RemoteResourceHandle methods, you can create and remove instances, create and remove actions, manipulate instances – group and ungroup them – and so on. The specified resource’s handle is initialized when the RemoteResourceManager’s getResourceHandle(resourceName) method is called.

195/309


public int createAction(String action, Guard guard) throws SecurityException

This creates an action by specifying its name:

• Arguments o action – action name o guard – if not null, it should be provided on each modification of

the action • Return values

o The unique (within the resource) identifier of the action • Exceptions

o SecurityException – thrown if the caller is denied access to the action

public int createInstance(String alias, Guard guard) throws SecurityException

This creates an instance of the resource:

• Arguments o alias – instance name o guard – if not null, it should be provided on each modification of

the action • Return values

o UserNode object representing the user or the group • Exceptions

o SecurityException – thrown if the caller is not granted permission to group users, or if such user or group does not exist

public void free()

This releases the resource handle from the pool when that handle is no longer needed.

public String getActionAlias(int actionId)

This gets the name of the specified action:

• Arguments o actionId – action identifier

• Return values o The name of the action

196/309


public int getActionId(String alias)

This gets the identifier of the specified action:

• Arguments o alias – action name

• Return values o The identifier of the action

public String[] getActions()

This gets the names of the actions for the resource:

• Return values o Enumeration of all action names

public String getAlias()

This gets the name of the resource:

• Return values o The name of the resource

public int[] getChildren(int instanceId)

This gets the identifiers of the children of the specified parent instance. It can be used only for an instance that owns grouped instances.

• Arguments o instanceId – the ID of the parent instance

• Return values o Enumeration of identifiers of the children, if there are any

public int getId()

This gets the resource identifier:

• Return values o The identifier of the resource

public String getInstanceAlias(int instanceId) throws SecurityException

This gets the instance name of the specified identifier:

197/309


• Arguments o instanceId – the instance identifier

• Return values o The name of the specified instance

public int getInstanceId(String alias)

This gets the instance identifier of the specified name:

• Arguments o alias – instance name

• Return values o The identifier of the instance

public int getParent(int instanceId)

This gets the identifier of the parent instance of the specified instance. The specified instance must have a parent.

• Arguments o instanceId – the instance identifier

• Return values o The identifier of the parent instance

public Permission getPermission(int actionId, int instanceId) throws SecurityException

This generates an instance of java.security.Permission used for authorization to access the specified instance using the specified action:

• Arguments o actionId – the action identifier o instanceId – the instance identifier

• Return values o Instance of java.security.Permission, used for authorization to

access the specified instance using the specified action • Exceptions

o SecurityException

public void groupInstance(int instanceId, Guard guard, int parentInstanceId, Guard instanceGuard) throws SecurityException

This groups the specified instance to the specified parent instance:

198/309


• Arguments o instanceId – the instance identifier o guard – instance guard o parentInstanceId – the identifier of the parent instance o instanceGuard – the guard of the parent instance


public void removeAction(int actionId, Guard guard) throws SecurityException

This removes the specified action:

• Arguments o actionId – action identifier o guard – action guard


public void removeInstance(int instanceId, Guard guard) throws SecurityException

This removes the specified instance. Only instances that are not grouped can be removed.

• Arguments o instanceId – the instance identifier o guard – instance guard


public void renameResource(String newAlias, Guard guard) throws SecurityException

This renames the resource:

• Arguments o newAlias – the new name for the resource o guard – the guard of the current resource


199/309


public void ungroupInstance(int instanceId, Guard guard) throws SecurityException

This ungroups the specified instance:

• Arguments o instanceId – the instance identifier o guard – the instance guard


For more information on how to use this manager, refer to <SAPj2eeEngine_install_dir>/docs/examples/services/security/resource_handle. The example can be started using the ResourceHandleExample script file, located in the <SAPj2eeEngine_install_dir>/docs/examples/services/security directory.

ProtectionDomainManager

Protection domain manager generates the right protection domains, used to classload files.

Users can modify protection domains using PolicyManager. PolicyManager provides the following functions:

• Creating the right protection domain on the basis of JDK java.policy file and the java.policy file of SAP J2EE Engine. This policy file is located in <SAPj2eeEngine_install_dir>/cluster/server/java.policy.

• Remote policy – denotes which user has rights to call a specified method. The remote policy file has the structure of the policy file, specified by the JDK PolicyFiles, located in <JDK_install_dir>/docs/guide/security/PolicyFiles. SAP J2EE Engine PolicyFiles are located in the <SAPj2eeEngine_install_dir>/alone/remote.policy and <SAPj2eeEngine_install_dir>/cluster/server/remote.policy directories.

Example:

grant codeBase “rmi.com.inqmy.services.admin.server.AdminFrameworkImpl” { permission java.lang.String “getAllManagers(int)”, “root”; };

In the above example, the name of the remote interface implementation class must be added to codeBase. In this case, the file name is

200/309


com.inqmy.services.admin.server.AdminFrameworkImpl. You must add rmi. before the name of the class. It is then declared as permission. The type of the value returned by the method (java.lang.String) and the name of the method (“getAllManagers(int)”) are declared. The last step is to specify the users or the groups to which the specified permission is granted – “root,” “Administrator,” and so on. If permissions are to be granted to more than one user, use commas to separate them – for example, “root, administrators, Guest.” When the server Security is started, the remote policy file is parsed and the service is considered as a resource (an object). An action “getAllManagers(int)” is created for this resource and is then granted to the specified resource users – “root, administrators, Guest.”

Use the java.policy files in the following directories to modify ProtectionDomainManager:

<SAPj2eeEngine_install_dir>/alone/java.policy <SAPj2eeEngine_install_dir>/cluster/dispatcher/java.policy <SAPj2eeEngine_install_dir>/cluster/server/java.policy

For an example on writing a policy file according to the JDK security specification, refer to <JDK_install_dir>/docs/guide/security/PolicyFiles.html

public void clearPermission(int userId, int roleId, int resourceId, int instanceId)

This removes all permissions on the role, resource and instance for the user specified by its ID:

• Arguments o userId – user identifier o roleId – action identifier o resourceId – resource identifier o instanceId – instance identifier

public void deny(String[] params)

This denies permission on the specified domain. Here, params are {domain_name, permission_type, permission_name}.

• Arguments o params – the parameters to deny

201/309


public void denyPermission(int userId, int roleId, int resourceId, int instanceId)

This denies permission on the specified user identifier on a role, resource or instance (or both):


public String[] getActions(String domainName, String permission)

This gets the actions of the specified permission on the specified domain:

• Arguments o domainName – domain name o permission – permission name

• Return values o All actions of the specified permission on the specified domain

public int[] getDeniedUsers(int roleId, int resourceId, int instanceId)

This gives the users that are not granted access to the specified role, resource or instance identifier (or both):

• Arguments o roleId – action identifier o resourceId – resource identifier o instanceId –instance identifier

• Return values o Enumeration of the identifiers of denied users


public String[] getDomainsNames()

This gets all domain names:

• Return values o Enumeration of domain names

202/309


public String[] getGrantedNames(String domainName, String permission, String action)

This gets the names of all users granted access to the specified permission and action on the specified domain:

• Arguments o domainName – domain name o permission – permission name o action – permission action

• Return values o Enumeration of users granted access to the specified permission in

the specified domain

public String[] getPermissionActions(String permission)

This gets the actions for the specified permission:

• Arguments o permission – permission name

• Return values o The names of the actions for the specified permission, if any

public String[] getPermissionInfo(String permission)

This gets an instance of UserNode about the specified permission:

• Arguments o permission – permission name

• Return values o UserNode – an object representing the permission information

public String[] getPermissionNames()

This gets all permissions names:

• Return values o Enumeration of all permission names

public String[] getPermissions(String domainName)

This gets all domain permissions:

• Arguments

203/309


o domainName – the domain name of the permissions to get • Return values

o Enumeration of all permissions for the specified domain name

public String[] getPermissionTargetName(String permission)

This gets the target name of permission. For example, Reflect has the target name suppressAccessChecks.

• Arguments o permission – permission the target names get

• Return values o Enumeration of the permission target names

public int[] getUsers(int roleId, int resourceId, int instanceId) throws SecurityException

This gets the identifiers of the users who have permission over the specified role, resource and instance:

• Arguments o roleId – action identifier o resourceId – resource identifier o instanceId – instance identifier

• Return values o Enumeration of all users who have permission over the specified

role, resource and instance • Exceptions

o SecurityException – thrown if the caller is not granted permission to group users, or if such user or group does not exist.

public void grant(String[] params)

This grants permissions to a specified domain. Here, params = {domain_name, permission_type, permission_name}

• Arguments o params – the permissions to grant

public void grantPermission(int userId, int roleId, int resourceId, int instanceId) throws SecurityException

This grants permission to the specified user of the specified role, resource or instance (or both):

204/309



For more information on how to use this manager, refer to <SAPj2eeEngine_install_dir>/docs/examples/services/security/protection_domain. The example can be started using the ProtectionDomainExample script file, located in the <SAPj2eeEngine_install_dir>/docs /examples/services/security directory.

Java Authentication and Authorization Service (JAAS)

SAP J2EE Engine Security Service handles remote logging using JAAS. The authorization of the user is performed using the login(String userName,

char[] password) method, which handles the user name and password and uses them to call the login() method from RemoteLogin. The authentication is then started by the commit() method, which creates principals and a password credential and calls the commit(Principal[] principals, PasswordCredential credential) method from RemoteLogin. The login module logout() method also uses the RemoteLogin logout() method and then clears out the user name and password. For more information on JAAS, refer to http://java.sun.com/products/jaas.

When the user attempts to log in remotely to SAP J2EE Engine, and does not own an account on the server, but only on an R/3 System, access to the system resources is granted. To obtain this, configure the connection with the R/3 System. For more information, refer to the Integration document. See also Administration Manual→Security Service.

Login System

The login system in the Security Service enables different users to log in to the server and, after a period, log out. A user logs in by specifying its user name and password. The login system checks the specified name and password. Based on these, it then gives the user different privileges to access the server resources, or refuses to log in the user, if the user is not a registered user. A user cannot log in if there are too many users logged in to the cluster, or if the user is disabled. The maximum number of login sessions is set in the security properties. Administrators have all privileges by default and they can force a log-out on any user logged in to the server at any time.

205/309


public void commit(Principal[] principals, PasswordCredential credential) throws SecurityException, RemoteException

This is used when a user attempts to login through the JAAS security service. This method performs a user authentication.

• Arguments o principals o credential

• Exceptions o SecurityException – thrown if the session is unknown o RemoteException

public Object login(Object sessionId, long expiration) throws SecurityException, RemoteException

This provides login by session ID for the specified expiration time in milliseconds:

• Arguments o sessionId – the identifier of the session o expiration – the log-in duration

• Return values o The session identifier

• Exceptions o SecurityException – thrown if the session is unknown o UnsupportedUserIdentifierException – thrown if the service does

not support identifiers of type long

public Object login(String name, char[] password) throws SecurityException, RemoteException

This logs in a user by specifying its name and password:

• Arguments o name – the user name o password – the user password

• Return values o Session identifier of the logged in user

• Exceptions o SecurityException – thrown if the caller is denied

206/309


public Object login(String name, char[] password, long expiration) throws SecurityException, RemoteException

This logs in a user by specifying its name and password for the specified expiration time in milliseconds. The default value for the expiration period is approximately one day.

• Arguments o name – the user name o password – the user password o expiration – the expiration period in milliseconds

• Return values o Session identifier of the logged in user

• Exceptions o SecurityException – thrown if the session is unknown

public void logout() throws SecurityException, RemoteException

This logs out the logged in user or service.

• Exceptions o SecurityException – thrown if the session is unknown

public void logout(long sessionId, long clientId) throws SecurityException, RemoteException

This logs out a user specified by the given session identifier. All credentials of the user stored in the security context are deleted.

• Arguments o sessionId – the unique long value responding to the user’s session o clientId – the session identifier of the client who invokes this

method • Exceptions

o SecurityException – thrown if the user with the given sessionId is not logged out

public void logout(Object sessionId, long clientId) throws SecurityException, RemoteException

This logs out a user specified by the given session identifier. All credentials of the user stored in the security context are deleted.

• Arguments

207/309


o sessionId – the unique long value responding to the user’s session o clientId – the session identifier of the client who invokes this

method • Exceptions

o SecurityException – thrown if the user with the given sessionId is not logged out

public long[] getSessions() throws SecurityException

This returns the identifiers of all sessions:

• Return values o All session identifiers


public String[] getSessionInfo(long sessionId) throws SecurityException

• Attributes o sessionId – the identifier of the session

• Return values o The session information


For more information on how to use this manager, refer to <SAPj2eeEngine_install_dir>/docs/examples/services/security/login. The example can be started using the LoginExample script file, located in the <SAPj2eeEngine_install_dir>/docs /examples/services/security directory.

SAP Integration Manager

SAP integration manager allows you to manage the connection between ABAP and J2EE Engine. The interface provides the following methods:

public void deleteConfiguration() throws java.lang.SecurityException, java.rmi.RemoteException

This removes the current SAP security configuration from the DB, if such exists. Calling this method will cause SAP security integration to be stopped if it was previously active.

• Exceptions

208/309


o java.lang.SecurityException - if an error occured during deletion of the current configuration, e.g. in the persistence layer

o java.rmi.RemoteException - if an error in the RMI layer occurs

public java.util.Properties exportR3SecurityProperties() throws java.lang.SecurityException, java.rmi.RemoteException

This gets the current configuration of SAP security configuration, as they ware used on calls to com.sap.security.Security.init() and com.sap.security.util.SAPBasis.init(). The properties returned are a subset of those returned by getConfiguration() (properties specific to the configuration wizard and it's graphical user interface will be omitted, since they are not relevant for the function of SAP security components). If the DBMS does not contain a configuration, or if it contains an emtpy configuration, this method will return an empty properties object. To determine whether the DBMS contains a configuration or not, use getConfiguration(), which will return null if and only if the DBMS does not contain a SAP security configuration.

• Return values o The current configuration of the SAP Security Integration.

• Exceptions o java.lang.SecurityException - if an error occured during retrieval

of the current configuration, e.g. in the persistence layer o java.rmi.RemoteException - if an error in the RMI layer occurs

public java.lang.String getActiveSapSystem () throws java.lang.SecurityException, java.rmi.RemoteException

This returns an identifier for the SAP system that is currently being used by SAP security components, or null if SAP security is not active

• Return values o An identifier for the SAP system that is currently being used by SAP

security components, or null if SAP security is not active. • Exceptions

o java.lang.SecurityException - if determination of the active system caused an error, e.g. in the RFC layer


209/309


public java.lang.String getClusterId() throws java.lang.SecurityException, java.rmi.RemoteException

This gets the integer ID of the cluster element on which this SapIntegrationManager is running as a string.

• Return values o The ID of the cluster element on which this SapIntegrationManager

is running as a string. • Exceptions

o java.lang.SecurityException - if the cluster ID could not be determined

public java.util.Properties getConfiguration() throws java.lang.SecurityException, java.rmi.RemoteException

This gets the current SAP security configuration from the DB, in a format that is suitable for initialization of the com.sap.security.um.wizard.WizardModel class (which can be used to initialize graphical configuration dialog). If no configuration is currently stored in the DBMS, null will be returned.

• Return values o The current SAP security configuration from the DB, in a format

that is suitable for initialization of the com.sap.security.um.wizard.WizardModel class (which can be used to initialize graphical configuration dialog). If no configuration is currently stored in the DBMS, null will be returned.

• Exceptions o java.lang.SecurityException - if an error occured during retrieval


public void importR3SecurityProperties(java.util.Properties p) throws java.lang.SecurityException, java.rmi.RemoteException

This validates and stores to the DBMS the given SAP security configuration p. If p passes formal validation, the current SAP security configuration will be stopped (if it was previously active), and the p is stored to the DBMS as new configuration. The new configuration will not be activated automatically.

The following properties are recognized:

Key Description Default Value

210/309


sapbasis.user User name (same as in JCO) n/a sapbasis.passwd Password (same as in JCO) n/a sapbasis.client SAP system client (same as in JCO) n/a sapbasis.lang Logon language (same as in JCO) n/a

sapbasis.ashost SAP application server host name (same as in JCO) n/a

sapbasis.sysnr SAP application server instance number (same as in JCO) n/a

sapbasis.mshost Message server host name (same as in JCO) n/a

sapbasis.r3name SAP application server system ID (same as in JCO) n/a

sapbasis.group SAP application server logon group (same as in JCO) n/a

sapbasis.gwhost Gateway host name (same as in JCO) n/a sapbasis.snc_mode Enable(1) or disable(0) SNC (same as in JCO) 0 sapbasis.snc_myname SNC name of the local PSE (same as in JCO) n/a

sapbasis.snc_partnername SNC name of the SAP application server (same as in JCO) n/a

sapbasis.snc_qop SNC quality of protection (same as in JCO) Max. available

sapbasis.snc_lib Path and file name of local security product, e.g. sapcrypto.dll (same as in JCO) n/a

sapbasis.acceptticket 1: ABAP stack accepts SAP Logon Tickets (profile parameter login/accept_sso2_ticket must be set to 1), 0: doesn't accept tickets

0

sapbasis.createticket 1: ABAP stack creates SAP Logon Tickets (profile parameter login/create_sso2_ticket must be set to 1), 0: doesn't create tickets

0

sapbasis.poolmaxsize Maximum size of JCO client pool 3

sapbasis.poolmaxwait Number of milliseconds to wait for a free client from the pool (after that time, a JCO.Exception will be thrown)

10000

You can also specify additional properties in the sapbasis.* namespace; they will be passed through to JCO as is.

• Atributes: o p – the the properties.

• Exceptions o java.lang.SecurityException - if p failed to pass formal validation,

or if the configuration could not be stored to the DBMS o java.rmi.RemoteException - if an error in the RMI layer occurs

211/309


public boolean isJaasUpdateNeeded() throws java.lang.SecurityException, java.rmi.RemoteException

This checks whether the current JAAS Login Module stack of the application "InQMyLoginSystem" needs to be updated, to reflect the current status of SAP security integration.

• Return values o True is the JAAS Login Module needs to be updated, false

otherwise. • Exceptions

o java.lang.SecurityException - if the JAAS configuration could not be determined


public void setConfiguration(java.util.Properties pWizard) throws java.lang.SecurityException, java.rmi.RemoteException

This stores pWizard into the DBMS as a new SAP security configuration. pWizard is expected to contain the marshaled data of an com.sap.security.um.wizard.WizardModel object (which could for example result from a graphical configuration dialog). Calling this method will cause SAP security integration to be stopped if it was previously active.

• Arguments o pWizard – the configuration properties.

• Exceptions o java.lang.SecurityException - if an error occured during storage


public void startSapSecurity() throws java.lang.SecurityException, java.rmi.RemoteException

This retrieves the current configuration from the DBMS, and (re-)starts SAP security. If startup was successful, the configuration is automatically started when the server restarts in the future.

• Exceptions o java.lang.SecurityException - if SAP security could not be started o java.rmi.RemoteException - if an error in the RMI layer occurs

212/309


public void stopSapSecurity() throws java.lang.SecurityException, java.rmi.RemoteException

This stops SAP security. If the DBMS contains a SAP security configuration, that configuration no longer is started automatically in the future when the server starts.

• Exceptions o java.lang.SecurityException - if SAP security could not be

stopped o java.rmi.RemoteException - if an error in the RMI layer occurs

public void updateJaasForSap() throws java.lang.SecurityException, java.rmi.RemoteException

This updates the JAAS Login Module configuration, so that users from the ABAP part can logon if integration is active, or that the login module for users from the ABAP part is removed if integration is not active (if it was the only module, the login module for local users is inserted to keep the system accessible).

• Exceptions o java.lang.SecurityException - if JAAS update failed o java.rmi.RemoteException - if an error in the RMI layer occurs

Example

This example introduces Security Service functions for different tasks, concerning various security restrictions and permissions. The example simulates adding and receiving money from a bank account and consists of two classes: Bank and Account. The Account class provides methods for adding money to a specific account, retrieving money or checking the current account’s status. The Bank class is the essential part of the security mechanism that controls the access to different accounts for different users.

Bank.java and Account.java files explained in this example are located in the <SAPj2eeEngine_install_dir>/docs/examples/services/security/bank directory. The example can be started using the BankExample script file, located in the <SAPj2eeEngine_install_dir>/docs/examples/services/security directory.

213/309


Account class

The example begins with a detailed explanation of the Account class’ methods:

/** * Add values to the account. * @param newmoney the amount to add to the account */ public void addMoney(int newmoney) throws SecurityException { // Check the permission of the logged in user over the account remoteHandle.checkPermission(Bank.act1, instanceId); // insert the value in the account money += newmoney; }

This addMoney() method adds money to an existing account.

/** * Reduces the amount of the account. * * @param newmoney the money to reduce the account with. */ public void takeMoney(int newmoney) throws SecurityException { // check the permission of the user over the account remoteHandle.checkPermission(Bank.act2, instanceId); // reduce the account with the value money -= newmoney; }

The method above retrieves money from an existing account.

/** * Shows the amount of the money in the account. * * @return money the amount of the account. */ public int showAccount() throws SecurityException { // check the permission of the user over the account. remoteHandle.checkPermission(Bank.act3, instanceId); // returns the amount of the account if the user has permission to view it. return money;

214/309


}

The method above checks the current account’s status.

remoteHandle.checkPermission(Bank.act1, instanceId) – in each of these methods, checks if the current user is authorized to access the specified account instance (instanceId) using a specified action (Bank.act1 ).

Bank Class

The security mechanism’s logic is explained below.

Bank(RemoteResourceManager, RemoteProtectionDomainManager, RemoteUserManager)

Using the constructor, the values of the managers needed to ensure security over the account are passed as parameters to the class:

public Bank(RemoteResourceManager ctx1, RemoteProtection DomainManager ctx2, RemoteUserManager remoteUserManager) throws SecurityException { // initialize the managers this.remoteResourceManager = ctx1; this.remoteDomainManager = ctx2; this.remoteUserManager = remoteUserManager;

A resource with the alias “Bank” is then created, and an integer identifier is returned by the createResource(String name, Guard guard) method.

// create resource that simulates the bank account resourceId = remoteResourceManager.createResource("Bank", null);

By invoking the getResourceHandle(int resourceId, Guard guard) method with resourceId passed as a parameter, a handle to the existing resource is created:

// get resource handle for the account remoteHandle = remoteResourceManager.getResourceHandle(resourceId);

By using the createAction(String name, Guard guard) method, different actions with unique identifiers and names are created:

act1 = remoteHandle.createAction("addMoney", null);

215/309


public void addAccount(String user, String accountName)

The method takes as arguments the name of the user trying to get permission to use the specified account. In the method’s body, an instance of Account object is created and is then added to a Vector:

// initialize new object that holds the current bank account data Account a = new Account(accountName); // add this new account to the holding data vector accounts.addElement(a);

The userId is returned by the getUserId() method only if the user exists and if the identifier is used by the grantPermission(int userId, int actionId, int resourceId, int instanceId) method of the RemoteUserManager interface. This method grants permission to the specified user to the specified resource instance:

// get user identifier that wants access to the account int userId = remoteUserManager.getUserId(user, true); // grant permissions to the user over the current account remoteDomainManager.grantPermission(userId, -1, resourceId, a.instanceId);

In this case, the action identifier is set to –1, which means that the user can access all methods of the current account instance.

public void removeAccount(String accountName)

The removeAccount() method takes an account name as an argument. It removes an account from the Vector element:

// remove the account accounts.removeElement(a);

RemoteHandle. checkPermission(int actionId, int instanceId) tests if the user is authorized to use the specified Account instance using this action:

// check the permission of the currently logged in user over the account remoteHandle.checkPermission(-1, a.instanceId);

If the user has authorization, the specified Account instance is removed.

The getAccount() method returns an account with a specified name, passed as a parameter. If the account instance doesn’t exist, a Security Exception is thrown.

216/309


public Account getAccount(String accountName)

A lookup of Security Service is performed for the remote application to function properly:

// look up security RemoteSecurity security = (RemoteSecurity) ((ServiceReference) ctx.lookup("security")).getServiceInterface(); security.getRemoteProtectionDomainManager(); login = security.getRemoteLoginManager(); users = security.getRemoteUserManager();

Two users with different login permissions are now trying to use the Account object:

login.login("Administrator", "".toCharArray()); // create user with privileges over the bank account userPass1 = users.createUser(true, userName1, null, new String[] {"root"}); // create user without rights over the accounts userPass2 = users.createUser(true, userName2, null, new String[]{"root"});

The second user does not have permissions, so an appropriate message is displayed. To run the security examples, you require a working SAP J2EE Engine and Dispatcher.

217/309


Servlets_jsp Service

Overview

Servlets_jsp Service represents both a container that manages servlets and an engine that uses JSP (Java Server Pages) technology. It is developed according to Java™ Servlet Specification, v2.2 and JavaServer Pages™ Specification, v1.1.

As a container of Web components, it implements the request-response model of interactions with clients. This request-response model is based on the behavior of the Hypertext Transfer Protocol (HTTP). Servlets_jsp Service and the HTTP Service provide the network services over which requests and responses are transmitted and processed.

Interfaces

This service does not provide any interfaces that could be directly used by clients. It is used with HTTP Service only.

Example

Servlets_jsp Service can be used only with HTTP Service. No example is presented here, since there is no specific usage to illustrate.

218/309


Shell Service

Overview

SAP J2EE Engine Shell Service provides Shell commands to control the running processes in the server and administer the cluster components using Console Administrator tool or Telnet for remote administration.

The Shell commands provided are created with mnemonic names and are gathered in groups, as most of the groups are named on the corresponding service in which they are registered. Most of the SAP J2EE Engine services use shell commands in their functions.

When the input data is typed on the command line, it is checked by name if it is a key word or a command for execution and the corresponding process is performed. If a shell command is typed, it is stored in the InputStream as an array of Strings, executed using the exec(..) method, and the result is stored in the OutputStream.

Before stopping the service, the command must be unregistered.

Interfaces

Command Interface

All Shell commands implement this interface. It provides methods for execution, getting name, group, shell provider, and help message of a command.

public void exec(Environment environment, InputStream input, OutputStream output, String[] params)

This method executes the input shell command:

• Arguments o Environment environment – specifies the environment (the

Environment interface is described below) o InputStream input – the input data, typed on the command line o OutputStream output – the data processed already

219/309


o String[] params – the typed input data after the command is stored as an array of strings

public String getName()

This method returns the name of the command. It is the first feature for searching.

• Return values o Returns a string that specifies the name of the command

public String getGroup()

This method returns the name of the group that the given command belongs to:

• Return values o Returns the corresponding group for this command

public String[] getSupportedShellProviderNames()

This method specifies to which Shell provider the corresponding command belongs. There are two options: InQMyShell or Telnet Shell provider.

• Return values o Returns an array of strings that specifies the corresponding Shell

provider

public String getHelpMessage()

This method returns a short help description message about the command:

• Return values o Returns a help message as a string

Environment Interface

This interface is implemented when setting the arguments of the Commmand interface exec(..) method.

public InputStream getInputStream()

This method returns the default system Input stream:

220/309


• Return values o Returns the default system input stream for this environment

public OutputStream getOutputStream()

This method returns the default system Output stream:

• Return values o Returns the default system output stream for this environment

public OutputStream getErrorStream()

This method returns the default system error stream:

• Return values o Returns the default system error stream for this environment

public String getVariable(String name)

This method returns the value of the name variable. All variables are of String type.

• Arguments o String name – the name of the variable

• Return values o Returns the value of the argument

public Object getContext()

This method returns an object that represents a context for this environment:

• Return values o Returns the requested object, containing some specific information

about the shell or its environment

221/309


SSL Service

Overview

The Secure Sockets Layer (SSL) Service represents the SSL Communication Protocol. More information about SSL can be found at htpp://java.sun.com/security/ssl/API_users_guide.html.

This service can be configured using the Visual Administrator. An implementation of the Institute for Applied Information Processing and the Communications Graz University of Technology (IAIK) provider is used. To use this service, you must obtain the following JAR files from your SAP J2EE Engine provider: iaik_jce.jar, iaik_jsse.jar, and iaik_ssl.jar, or download them from http://jcewww.iaik.at/download/evaluation/index.php and put them in the following directories:

• ../admin/lib/ • ../alone/additional-lib/ • ../cluster/dispatcher/additional-lib/ • ../cluster/all dispatchers/additional-lib/ • ../cluster/server/additional-lib/ • ../cluster/all servers/additional-lib/

or in the directory pointed by the CLASSPATH variable. Start Keystore and SSL Services on both dispatcher and server nodes. Keystore Service must be started first.

Example:

1. Start SAP J2EE Engine Dispatcher and Server.

2. Try to log in as localhost by typing the following text in a browser:

https://localhost/

You cannot use this service remotely. For more infomation refer, to the Administration Manual.

222/309


Interfaces


223/309


Telnet Service

Overview

SAP J2EE Engine Telnet Service enables remote Shell administration using Telnet clients and a Telnet protocol (RFC#854). It is a session service, therefore it is installed on both server and dispatcher nodes for administration, and supports almost all Telnet clients.

The remote administration can be performed if the remote machine (in the Local Area Network) has an installed and running SAP J2EE Engine, and the local one has a Telnet client from which to connect.

The dispatcher node of the server listens to newcomer Telnet clients on an opened server socket with a specific port, defined in the property file of the service. By default, it is 2323, but this value can be changed. For each incoming client, a socket is opened to establish connections. The Telnet client sends requests in accordance with the Telnet protocol and the corresponding Shell commands for the server.

You can use the JUMP shell command to stop the current cluster element administration and to start the administration of another one.

Interfaces

This service does not provide any interfaces that could be directly used by clients.

224/309


Transaction Service (TS)

Overview

Transaction Service manages global transactions in SAP J2EE Engine. It is developed entirely according to JTA 1.0.1. Specification.

A transaction represents a sequence of information treated as a unit to satisfy a request and to ensure database integrity. Transactions have the following features, known as ACID characteristics:

• Atomicity – if the transaction fails, all effects it causes are rolled back. • Consistency – the effects of a transaction preserve database integrity. • Isolation – all transactions are executed independently from one

another. The interim results are not visible to other transactions. • Durability – the results of a transaction are durable and cannot be lost

except when an event that is crucial to the database itself occurs.

Transactions can run locally on a single host, or they can be distributed among several hosts. To provide flawless execution and lack of data losses in distributed environment, Transaction Service supports the two-phase-commit (2PC) protocol for global transactions. The 2PC involves a preparation phase and a commit phase, which is completed only when all branches of the transaction are prepared to commit. This preserves the atomicity of the distributed transactions and ensures the consistency of the data.

The implementations of two basic interfaces in Transaction Service provide its functions – UserTransaction interface and TransactionManager interface.

Interfaces

UserTransaction Interface

The javax.transaction.UserTransaction interface is implemented in Transaction Service to enable the applications to take control of the transaction boundaries. Java client programs or EJBs can use this interface.

A list of methods is provided below.

225/309


void begin() throws NotSupportedException, SystemException

This method creates a new transaction and associates it to the current thread:

• Exceptions o NotSupportedException – thrown if the current thread is already

associated with a transaction, or the implementation of the Transaction Manager does not support nested transactions

o SystemException – thrown if an unexpected error occurs

void commit() throws RollbackException, HeuristicMixedException, HeuristicRollbackException, java.lang.SecurityException, java.lang.IllegalStateException, SystemException

This method finishes the transaction associated with the current thread:

• Exceptions o RollbackException – thrown if the transaction has been rolled back

and not committed o HeuristicMixedException – thrown to indicate that a heuristic

decision was made and that some relevant updates have been committed while others have been rolled back

o HeuristicRollbackException – thrown to indicate that a heuristic decision was made and that some relevant updates have been rolled back

o java.lang.SecurityException – thrown if the current thread is not allowed to commit the transaction

o java.lang.IllegalStateException – thrown if the current thread is not associated with a transaction


int getStatus() throws SystemException

This method provides the status of the transaction associated with the current thread:

• Return value o Returns the transaction status. If no transaction is associated with

the current thread, this method returns the Status.NoTransaction value.

• Exceptions o SystemException – thrown if an unexpected error occurs

226/309


void rollback() throws java.lang.IllegalStateException, java.lang.SecurityException, SystemException

This method rolls back the transaction associated with the current thread:

• Exceptions o java.lang.IllegalStateException – thrown if the current thread

is not associated with a transaction o java.lang.SecurityException – thrown if the current thread is not

allowed to roll back the transaction o SystemException – thrown if an unexpected error occurs

void setRollbackOnly() throws java.lang.IllegalStateException, SystemException

This method modifies the transaction associated with the current thread so that the only outcome of the transaction is to roll back the transaction:


is not associated with a transaction o SystemException – thrown if an unexpected error occurs

void setTransactionTimeout(int seconds) throws SystemException

This method modifies the value of the timeout value that is associated with the transactions started by the current thread using the begin() method. If the method is not called by an application, a default value is used instead.

• Arguments o This method takes as a parameter the value of the timeout in

seconds. If the value is zero, the transaction service restores the default value.


TransactionManager Interface

The javax.transaction.TransactionManager interface is implemented in Transaction Service to enable the application server to manage the transaction demarcation of the current application.

A list of methods is provided below.

227/309


void begin() throws NotSupportedException, SystemException

This method creates a transaction and associates it with the current thread:

• Exceptions o NotSupportedException – thrown if the current thread is already

associated with a transaction, or the implementation of the Transaction Manager does not support nested transactions


void commit() throws RollbackException, HeuristicMixedException, HeuristicRollbackException, java.lang.SecurityException, java.lang.IllegalStateException, SystemException

This method finishes the transaction associated with the current thread. When the method finishes, the current thread is associated with no transaction.

• Exceptions o RollbackException – thrown if the transaction has been rolled back

and not committed o HeuristicMixedException – thrown to indicate that a heuristic

decision was made and that some relevant updates have been committed while others have been rolled back

o HeuristicRollbackException – thrown to indicate that a heuristic decision was made and that some relevant updates have been rolled back

o java.lang.SecurityException – thrown if the current thread is not allowed to commit the transaction

o java.lang.IllegalStateException – thrown if the current thread is not associated with a transaction


int getStatus() throws SystemException

This method provides the status of the transaction associated with the current thread:

• Return value o Returns the transaction status. If no transaction is associated with

the current thread, this method returns the Status.NoTransaction value.


228/309


Transaction getTransaction() throws SystemException

This method obtains the transaction object that represents the transaction context of the calling thread:

• Return value o Returns the transaction object that represents the transaction

context of the calling thread • Exceptions


void resume(Transaction tobj) throws InvalidTransactionException, java.lang.IllegalStateException, SystemException

This method resumes the transaction context association of the calling thread with the transaction represented by the supplied Transaction object:

• Arguments o Transaction tobj – an object that represents the actual transaction

to be resumed • Exceptions

o InvalidTransactionException – thrown if the parameter transaction object contains an invalid transaction

o java.lang.IllegalStateException – thrown if the current thread is already associated with another transaction


void rollback() throws java.lang.IllegalStateException, java.lang.SecurityException, SystemException

This method rolls back the transaction associated with the current thread:


is not associated with a transaction o java.lang.SecurityException – thrown if the current thread is not

allowed to roll back the transaction o SystemException – thrown if an unexpected error occurs

void setRollbackOnly() throws java.lang.IllegalStateException, SystemException

This method modifies the transaction associated with the current thread so that the only outcome of the transaction is to roll back the transaction:

229/309



is not associated with a transaction o SystemException – thrown if an unexpected error occurs

void setTransactionTimeout(int seconds) throws SystemException

This method modifies the value of the timeout value that is associated with the transactions started by the current thread using the begin() method. If the method is not called by an application, a default value is used instead.

• Arguments o This method takes as parameter the value of the timeout in

seconds. If the value is zero, the transaction service restores the default value.

• Exception o SystemException – thrown if an unexpected error occurs

Transaction suspend() throws SystemException

This method suspends the transaction currently associated with the calling threads and returns the Transaction object representing the transaction context that is being suspended:

• Return value o This method returns the Transaction object that represents the

suspended transaction. If the calling thread is associated with no transaction, the null object reference is returned.


Example

The next example illustrates the usage of the commit() and rollback() methods of the UserTransacation interface. The source of the example is available in <SAPj2eeEngine_install_dir>/docs/examples/services/ts/.

To run the example, you must first deploy on the server bench.ear, which is located in the <SAPj2eeEngine_install_dir>/docs/examples/services/ts/ directory. The example can then be started using the TsClient script file, located in the same directory.

230/309


First, a lookup of the UserTransaction object is performed, using the init() method:

UserTransaction userTransaction = null; ... ... userTransaction= (UserTransaction)ctx.lookup("java:comp/UserTransaction"); Then the transaction is executed through the process() method: try { userTransaction.begin(); dump("UserTransaction started."); //perform some functionality userTransaction.commit(); dump("Client tx committed."); } catch(Exception exc) { exc.printStackTrace(); dump("FAIL"); try { // check transaction status if (userTransaction.getStatus() != Status.STATUS_NO_TRANSACTION) { // rollback the transaction userTransaction.rollback(); } } catch(Exception e) { dump("Example failed: " + e); e.printStackTrace(); } }

The transaction begins with userTransaction.begins(). If an exception is thrown in the body of the transaction, and the transaction is associated with the current thread, a userTransaction.rollback() is executed. Otherwise, the userTransaction.commit() is performed, and the transaction completes successfully.

231/309


Chapter 5 Developing Third-Party Visualizations

of SAP J2EE Engine Tools • Overview

• Config Tool

• SAP J2EE Engine Installation and Uninstallation Programs

232/309


Overview

SAP J2EE Engine distribution contains two XML-based tools – the Installation and Uninstallation Programs, and Config Tool. Both tools are provided with two visualizations – GUI and text only. Because they are based on XMLs, another visualization can be developed for these tools. More importantly, each of the two tools can be integrated into a more complicated system.

This section consists of two sections that describe the XMLs used by these tools. To create a third-party visualization, or fit one of the tools into another system, you must preserve the configuration of these tools. The XML files used by these tools must be read and generated properly. The structure of all necessary XML files is described in detail in this document.

For more information about the Installation and Uninstallation Programs, refer to the Installation Manual. For more information about the usage of SAP J2EE Engine Config Tool, refer to the Administration Manual.

233/309


Config Tool

batchconfig.xml

batchconfig.xml is an XML file that is generated during the process of configuring SAP J2EE Engine with a GUI, non-GUI, or a third-party tool. The possibilities for modifications, displayed through these tools, are executed by creating and passing the batchconfig.xml to the <SAPj2eeEngine_install_dir>/configtool/batchconfig script. To make use of it, you must have an installed SAP J2EE Engine on your machine.

batchconfig.xml must have the following structure:

<!DOCTYPE config [ <!ELEMENT config (installed-dir, make-new-dispatcher*, make-new-server*, cluster-element*)> <!ELEMENT installed-dir (#PCDATA)> <!ELEMENT make-new-dispatcher (#PCDATA)> <!ATTLIST make-new-dispatcher name CDATA #REQUIRED> <!ELEMENT make-new-server (#PCDATA)> <!ATTLIST make-new-server name CDATA #REQUIRED> <!ELEMENT cluster-element (managers, services, service-daemon-settings?)> <!ATTLIST cluster-element name CDATA #REQUIRED> <!ATTLIST cluster-element service-daemon CDATA #REQUIRED> <!ATTLIST cluster-element debug-mode CDATA #IMPLIED> <!ATTLIST cluster-element debug-port CDATA #IMPLIED> <!ELEMENT managers (manager*)> <!ELEMENT manager (property*)> <!ATTLIST manager name CDATA #REQUIRED> <!ELEMENT property (#PCDATA)> <!ATTLIST property key CDATA #REQUIRED> <!ATTLIST property value CDATA #REQUIRED> <!ELEMENT services (service*)> <!ELEMENT service (property*)> <!ATTLIST service startup-mode CDATA #REQUIRED> <!ATTLIST service name CDATA #REQUIRED> <!ELEMENT service-daemon-settings (name, main-class, root-dir, parameters, timeout, port, java-path, java-parameters)> <!ELEMENT name (#PCDATA)> <!ELEMENT main-class (#PCDATA)> <!ELEMENT root-dir (#PCDATA)> <!ELEMENT parameters (#PCDATA)> <!ELEMENT timeout (#PCDATA)> <!ELEMENT port (#PCDATA)> <!ELEMENT java-path (#PCDATA)> <!ELEMENT java-parameters (#PCDATA)> ]>

234/309


The DOCTYPE field must be filled properly for the XML to be parsed correctly. All fields are explained in detail below.

<!ELEMENT config (installed-dir, make-new-dispatcher*, make-new-

server*, cluster-element*)> – describes the root element. It must have the name config.

<!ELEMENT installed-dir (#PCDATA)> – specifies the directory where SAP J2EE Engine has been installed.

<!ELEMENT make-new-dispatcher (#PCDATA)> – specifies the new dispatcher to be added.

<!ATTLIST make-new-dispatcher name CDATA #REQUIRED> – specifies the name of the added dispatcher.

<!ELEMENT make-new-server (#PCDATA)> – specifies the new server to be added.

<!ATTLIST make-new-server name CDATA #REQUIRED> – specifies the name of the added server.

<!ELEMENT cluster-element (managers, services, service-daemon-

settings?)> – describes a cluster element with its managers, services, and service daemon settings.

<!ATTLIST cluster-element name CDATA #REQUIRED> – specifies the name of the cluster element.

<!ATTLIST cluster-element service-daemon CDATA #REQUIRED> – specifies if the cluster element is set as NT/2000 Service or Unix Daemon. This attribute has a boolean value – true or false.

<!ATTLIST cluster-element debug-mode CDATA #IMPLIED> – specifies if the server node or “alone” configuration is set in remote debug mode. This attribute has yes or no value. It does not concern dispatcher nodes.

<!ATTLIST cluster-element debug-port CDATA #IMPLIED> – specifies the port through which debugger clients remote connections are established. It does not concern dispatcher nodes.

<!ELEMENT managers (manager*)> – describes the cluster element managers.

235/309


<!ELEMENT manager (property*)> – describes the properties of a particular manager.

<!ATTLIST manager name CDATA #REQUIRED> – specifies the name of a particular manager.

<!ELEMENT property (#PCDATA)> – specifies a property that can be used to configure it.

<!ATTLIST property key CDATA #REQUIRED> – specifies the key (name) of the property to configure it correctly.

<!ATTLIST property value CDATA #REQUIRED> – specifies the value of the property to configure it correctly.

<!ELEMENT services (service*)> – describes the cluster element services.

<!ELEMENT service (property*)> – describes the properties of a particular service.

<!ATTLIST service startup-mode CDATA #REQUIRED> – specifies the startup mode of the service. There are three options – always (the service is started with the start of the server), automatic (the service is started on demand of a client application), and manual (the service is started manually from Visual Administrator or Console Administrator).

<!ATTLIST service name CDATA #REQUIRED> – specifies the name of the service.

<!ELEMENT service-daemon-settings (name, main-class, root-dir,

parameters, timeout, port, java-path, java-parameters)> – describes the settings necessary to run a cluster element as a NT/2000 Service or Unix Daemon.

<!ELEMENT name (#PCDATA)> – specifies a mnemonic name for this element.

<!ELEMENT main-class (#PCDATA)> – specifies the main class to run.

<!ELEMENT root-dir (#PCDATA)> – specifies the directory where the particular cluster element is installed.

<!ELEMENT parameters (#PCDATA)> – specifies the main class input parameters, if needed.

236/309


<!ELEMENT timeout (#PCDATA)> – specifies the time (in milliseconds) after which the element is stopped by the system if it has failed to shut down.

<!ELEMENT port (#PCDATA)> – specifies the port to be used when shutting down the element. When the operating system sends a signal for shutdown, the program sends a specially generated random key on this port. This key was generated when the element was started and the same key is used at shutdown for verification. The program waits until the specified timeout passes. After the timeout, if the element is still running, it is forced to shut down.

<!ELEMENT java-path (#PCDATA)> – specifies the classpath to the JDK bin directory.

<!ELEMENT java-parameters (#PCDATA)> – specifies additional parameters to be passed to the JVM.

The example below shows a sample batchconfig.xml file.

Example: <config> <installed-dir>C:\SAP J2EE Engine 6.20\ </installed_dir> <make-new-dispatcher name="Dispatcher 3"> </make-new-dispatcher> <make-new-server name="Server 30"> </make-new-server> <cluster-element name="Dispatcher" service-daemon="true"> <managers> <manager name="clustermanager"> <property key="JoinPort" value="2077"></property> </manager> <manager name="theadmanager"> <property key="MaxThreadCount" value="200"></property> </manager> </managers> <services> <service name="telnet"> <property key="port" value="2323"></property> </service> </services> <service-daemon-settings> <name>cluster\dispatcher</name> <root-dir>C:\SAP_J2EEngine6.20\cluster\dispatcher</root- dir> <java-path>C:\Program Files\JavaSoft\JRE\1.3\bin\java </java-path> <java-parameters>-classpath ".;./system-lib/ boot.jar;./system-lib/jndi1.2.jar;./system-lib/

237/309


iiop.jar;./system-lib/jaas.jar" -Djava. security.policy\=.\\ java.policy -Dorg. omg.CORBA.ORBClass\=com.inqmy.services.iiop.internal.ORB -Dorg. omg.CORBA.ORBSingletonClass\=com.inqmy.services.iiop.internal .ORB -Djavax. rmi.CORBA.PortableRemoteObjectClass\=com.inqmy.system.Porta bleRemoteObjectProxy -Djavax. rmi.CORBA.UtilClass\=com.inqmy.system.UtilDelegateProxy </java-parameters> <main-class>com.inqmy.boot.Start</main-class> <parameters> </parameters> <port>123</port> <timeout>10000</timeout> </service-daemon-settings> </cluster-element> </config>

238/309


SAP J2EE Engine Installation and Uninstallation Programs

This section is oriented to developers who are appointed to create another visualization or system user interaction that installs or uninstalls SAP J2EE Engine. This installation type is based on the SAP J2EE Engine installation concepts. Third-party tools can be used instead of the user interfaces provided by SAP J2EE Engine (GUI or non-GUI based). A third-party tool may implement a different user interface on batch setup level. It can be used in to fit the server installation as a part of a more complicated system, or to change its user interface according to your requirements.

The configuration of the installed SAP J2EE Engine must remain the same, no matter what type of installation is used. All SAP J2EE Engine core batch tools must be used properly, and all XML files must be read and generated properly. The structure of these XML files is described below. The SAP J2EE Engine installation and uninstallation concept, and its necessary components, are described below.

239/309


SAP J2EE Engine Installation Concept

This graphic presents the SAP J2EE Engine installation concept. Installation settings are stored in XML files, which provides greater flexibility and easier reconfiguration.

In accordance with the Project.xml file, the Installation Generator tool creates an archive ZIP file. This archive file consists of all the files necessary for the installation, including manifest.xml file. The manifest.xml file contains the information, specifying the files that are crypted, and how they are created. This file defines all system components, and therefore third-party tools should read it properly. The definition of manifest.xml is described below.

SAP J2EE Engine installation tool generates a BatchSetup.xml. In accordance with this file, the Batch Setup tool installs SAP J2EE Engine. Therefore, if a third-party tool is used, a proper BatchSetup.xml file should be generated and passed to the Batch Setup tool. BatchSetup.xml is described below.

After the installation process completes, install_log.xml file is generated. It contains information about the installed server configuration. This file is

240/309


necessary for the uninstallation process. SAP J2EE Engine uninstallation tool reads from the install_log.xml information to determine the components that have been installed. Therefore, if a third-party tool is used instead, this file should be read properly. install_log.xml is described below.

For the needs of the uninstallation process, uninstall.xml file must be generated either by SAP J2EE Engine or by a third-party user interface tool. This XML file contains the information about the uninstallation process – identifying the installed groups that must be uninstalled. After the uninstallation is completed, the status is stored back in the same file, containing the groups that were deleted successfully and those that encountered problems while uninstalling. In this way, uninstall.xml can be reused further if specific components are not uninstalled successfully. Therefore, if a third-party tool is used for the uninstallation procedure, this file should be generated properly and be passed to the Batch Uninstall core tool. The definition of uninstall.xml is described below.

Manifest.xml

Third-party tools must use this XML document for the SAP J2EE Engine installation process. A third-party tool reads manifest.xml file so that the SAP J2EE Engine components can be installed properly. Then, BatchSetup.xml must be generated and it must be given as a parameter to the Batch Setup core tool. manifest.xml defines all system components, and it must have the following structure:

<!DOCTYPE manifest [ <!ELEMENT manifest (product-name?, default-install-dir?, default-program-folder?, version-min?, version-max?, install-types?)> <!ELEMENT product-name (#PCDATA)> <!ELEMENT crypted (#PCDATA)> <!ELEMENT default-install-dir (#PCDATA)> <!ELEMENT default-program-folder (#PCDATA)> <!ELEMENT version-min (#PCDATA)> <!ELEMENT version-max (#PCDATA)> <!ELEMENT install-types (install-type*)> <!ELEMENT install-type (install-groups)> <!ATTLIST install-type name CDATA #REQUIRED description CDATA #REQUIRED size CDATA #REQUIRED> <!ELEMENT install-groups (install-group*)> <!ELEMENT install-group (install-files, install-scripts, install-shortcuts, properties)> <!ATTLIST install-group name CDATA #REQUIRED group-dir CDATA #REQUIRED description CDATA #REQUIRED size CDATA #REQUIRED> <!ELEMENT install-files (install-file*)> <!ELEMENT install-file (#PCDATA)> <!ATTLIST install-file name CDATA #REQUIRED source CDATA #REQUIRED

241/309


target CDATA #REQUIRED crypted CDATA #REQUIRED os CDATA #IMPLIED upgradable CDATA #IMPLIED> <!ELEMENT install-scripts (install-script*)> <!ELEMENT install-script (data)> <!ATTLIST install-script name CDATA #REQUIRED os CDATA #IMPLIED> <!ELEMENT data (#PCDATA)> <!ELEMENT install-shortcuts (install-shortcut*)> <!ELEMENT install-shortcut (#PCDATA)> <!ATTLIST install-shortcut name CDATA #REQUIRED icon CDATA #REQUIRED source CDATA #REQUIRED args CDATA #REQUIRED destination CDATA #REQUIRED work-dir CDATA #REQUIRED description CDATA #REQUIRED os CDATA #IMPLIED> <!ELEMENT properties (property*)> <!ELEMENT property (#PCDATA)> <!ATTLIST property key CDATA #REQUIRED value CDATA #REQUIRED> ]>


<!ELEMENT manifest (product-name?, default-install-dir?, default-

program-folder?, version-min?, version-max?, install-types?)> – this is the root element. It must have the name manifest.

<!ELEMENT product-name (#PCDATA)> – specifies the valid product name that is displayed in the GUI installation tool.

<!ELEMENT crypted (#PCDATA)> – specifies if the installation is crypted with serial number.

<!ELEMENT default-install-dir (#PCDATA)> – specifies the path to the folder in which the product is installed, if the client does not specify one.

<!ELEMENT default-program-folder (#PCDATA)> – specifies the path to the folder in which the shortcuts (for Windows) are saved.

<!ELEMENT version-min (#PCDATA)> – specifies the minimum server version from which the upgrading process can be performed.

<!ELEMENT version-max (#PCDATA)> – specifies the maximum server version to which the system administrator can upgrade.

<!ELEMENT install-types (install-type*)> – describes the installation types. For example, Cluster or Stand-alone.

<!ELEMENT install-type (install-groups)> – describes the groups that are installed in accordance with the type of installation.

242/309


<!ATTLIST install-type name CDATA #REQUIRED description CDATA

#REQUIRED size CDATA #REQUIRED> – specifies the type of installation by its name, description, and size in bytes.

<!ELEMENT install-groups (install-group*)> – describes the groups available for the type of installation.

<!ELEMENT install-group (install-files, install-scripts, install-

shortcuts, properties)> – describes the chosen group with the files, scripts, shortcuts, and properties to be used during the installation.

<!ATTLIST install-group name CDATA #REQUIRED group-dir CDATA

#REQUIRED" description CDATA #REQUIRED size CDATA #REQUIRED> – specifies the group by name, group directory, description, and size.

The following tags describe internal information, which does not concern the development of third-party tools:

<!ELEMENT install-files (install-file*)> <!ELEMENT install-file (#PCDATA)> <!ATTLIST install-file name CDATA #REQUIRED source CDATA #REQUIRED target CDATA #REQUIRED crypted CDATA #REQUIRED os CDATA #IMPLIED upgradable CDATA #IMPLIED > <!ELEMENT install-scripts (install-script*)> <!ELEMENT install-script (data)> <!ATTLIST install-script name CDATA #REQUIRED os CDATA #IMPLIED> <!ELEMENT data (#PCDATA)> <!ELEMENT install-shortcuts (install-shortcut*)> <!ELEMENT install-shortcut (#PCDATA)> <!ATTLIST install-shortcut name CDATA #REQUIRED icon CDATA #REQUIRED source CDATA #REQUIRED args CDATA #REQUIRED destination CDATA #REQUIRED work-dir CDATA #REQUIRED description CDATA #REQUIRED os CDATA #IMPLIED>

<!ELEMENT properties (property*)> – describes the group properties. For example: dispatcher, server, and alone.

<!ELEMENT property (#PCDATA)> – specifies a property of group to be installed.

<!ATTLIST property key CDATA #REQUIRED value CDATA #REQUIRED> – specifies property key and value of group to be installed.

The example below describes how to use manifest.xml file. The whole manifest.xml can be found at distr.zip file, which is one of the SAP J2EE Engine distribution installation files.

243/309


Example: <manifest> <product-name> SAP J2EE Engine 6.20 Cluster </product-name> <crypted> false </crypted> <default-install-dir> SAP_J2EEngine6.20 </default-install-dir> <default-program-folder> SAP J2EE Engine 6.20 <version-min> 6.20 b1 </version-min> <version-max> 6.20 b6 </version-max> </default-program-folder> <install-types> <install-type description="alone" name="alone" size="40489793"> <install-groups> <install-group description="Installs a Standalone Server. Select the Properties button to modify the Standalone Server initial properties." group-dir="alone/" name="alone" size="9475294"> <install-files> <install-file crypted="false" name="inqmy-frame-lib.jar7111" os="Windows;Unix;Solaris;Netware" target="alone/lib/inqmy-frame-lib.jar" upgradable=”false”> </install-file> </install-files> <install-scripts> <install-script name="alone/go" os="Windows;Unix;Solaris;Netware"> <data> set MEMORY="64M" "%JAVA_HOME% -classpath \".;./system-lib/boot.jar;./system-lib/jndi1.2.jar;./system-lib/iiop.jar;./system-lib/jaas.jar\" -Xmx%MEMORY% -Dmemory.manager=%MEMORY% -Djava.security.policy=.\\java.policy -Dorg.omg.CORBA.ORBClass=com.inqmy.system.ORBProxy -Dorg.omg.CORBA.ORBSingletonClass=com.inqmy.services.iiop.internal.ORB -Djavax.rmi.CORBA.PortableRemoteObjectClass=com.inqmy.system.PortableRemoteObjectProxy -Djavax.rmi.CORBA.UtilClass=com.inqmy.system.UtilDelegateProxy com.inqmy.boot.Start $1$ $2$ $3$ $4$ $5$ $6$ $7$ $8$ $9$" </data> </install-script> </install-scripts> <install-shortcuts>

244/309


<install-shortcut args="" description="" destination="" icon="alone/alone.ico" name="Stand Alone Server" os="Windows;Unix;Solaris;Netware" source="alone/go" work-dir=""> </install-shortcut> </install-shortcuts> <properties> <property key="ClusterElementNameC" value="Dispatcher One"> </property> <property key="MemoryElement" value="false"> </property> </properties> </install-group> </install-groups> </install-type> </install-types> </manifest>

BatchSetup.xml

The XML document that a third-party tool must provide to the batch Setup tool during the installation of SAP J2EE Engine must have the following structure:

<!DOCTYPE install [ <!ELEMENT install (user-name?, company-name?, installed-program-folder?, installed-dir?, java-VM-path?, max-java-heap-size?, installed-groups?)> <!ELEMENT user-name (#PCDATA)> <!ELEMENT company-name (#PCDATA)> <!ELEMENT installed-program-folder (#PCDATA)> <!ELEMENT installed-dir (#PCDATA)> <!ELEMENT java-VM-path (#PCDATA)> <!ELEMENT max-java-heap-size (#PCDATA)> <!ELEMENT installed-groups (install-group*)> <!ELEMENT install-group (properties)> <!ATTLIST install-group name CDATA #REQUIRED group-dir CDATA #REQIRED description CDATA #REQUIRED size CDATA #REQUIRED> <!ELEMENT properties (property*)> <!ELEMENT property (#PCDATA)> <!ATTLIST property key CDATA #REQUIRED value CDATA #REQUIRED> ]>


<!ELEMENT install (user-name?, company-name?, program-folder?, installed-dir?, java-VM-path?, max-java-heap-size?, installed-groups?)> – this is the root element. It must have the name install.

<!ELEMENT user-name (#PCDATA)> – specifies a valid user name.

245/309


<!ELEMENT company-name (#PCDATA)> – specifies a company name, for which the installation is made.

<!ELEMENT installed-program-folder (#PCDATA)> – specifies a folder in which the shortcuts (for Windows) are installed.

<!ELEMENT installed-dir (#PCDATA)> – specifies a folder in which the product is installed.

<!ELEMENT java-VM-path (#PCDATA)> – specifies the path to Java Virtual Machine.

<!ELEMENT max-java-heap-size (#PCDATA)> – specifies the maximum java heap size (in megabytes) for dispatcher, server, and “alone” configuration running.

<!ELEMENT installed-groups (install-group*)> – describes which groups are installed.

<!ELEMENT install-group (properties)> – describes the properties for the installation of a group.

<!ATTLIST install-group name CDATA #REQUIRED group-dir CDATA #REQIRED"

description CDATA #REQUIRED size CDATA #REQUIRED> – specifies a group. group-dir specifies the relative path of an installed group from the installed program folder. description represents a short description of a group. size is the group size in bytes.

<!ELEMENT properties (property*)> – describes the properties (if any exist) of a group. Only “dispatcher,” “server,” and “alone” groups have properties.

<!ELEMENT property (#PCDATA)> – specifies the property of an installed group.

<!ATTLIST property key CDATA #REQUIRED value CDATA #REQUIRED> – specifies property key and value of an installed group.

The example below describes how BatchSetup.xml file can be used. The whole file can be examined after executing of the extract command from the GUI or console installation procedure of the SAP J2EE Engine installation.

Example: <install> <user-name> krassik

246/309


</user-name> <company-name> </company-name> <installed-program-folder> SAP J2EE Engine 6.20 </installed-program-folder> <installed-dir> C:\SAP_J2EEngine6.20\ </installed-dir> <java-VM-path> C:\jdk1.3\jre\bin\java </java-VM-path> <max-java-heap-size> 64 </max-java-heap-size> <installed-groups> <install-group description="Installs SAP J2EE Engine Visual Administrator. This GUI-based tool provides for the server administration at runtime." group-dir="admin/" name="admin" size="6877934"> <properties> </properties> </install-group> <install-group description="Installs a Server node of SAP J2EE Engine cluster. To create a working cluster, you must include the Dispatcher component group too. Select the Properties button (applied to the Visual Installation only) to modify the Server node initial properties." group-dir="cluster/server/" name="server" size="9440429"> <properties> <property key="JoinPort" value="2078"> </property> <property key="NoticeLogFileName" value="./managers/log/cluster/NOTICE.log"> </property> <property key="WarningLogFileName" value="./managers/log/cluster/WARNING.log"> </properties> </install-group> </installed-groups> </install>

install_log.xml

This XML document is created during the SAP J2EE Engine installation process. Its information must be used for the uninstallation process from third-party tools. The file must have the following structure:

<!DOCTYPE install [ <!ELEMENT install (product-name, installed-dir, installed-groups, installed-program-folder)> <!ELEMENT product-name (#PCDATA)>

247/309


<!ELEMENT installed-program-folder (#PCDATA)> <!ELEMENT installed-dir (#PCDATA)> <!ELEMENT install-groups (install-group*)> <!ELEMENT install-group (installed-files, install-scripts, install-shortcuts, properties)> <!ATTLIST install-group name CDATA #REQUIRED group-dir CDATA #REQUIRED description CDATA #REQUIRED size CDATA #REQUIRED> <!ELEMENT install-files (install-file*)> <!ELEMENT install-file (#PCDATA)> <!ATTLIST install-file name CDATA #REQUIRED source CDATA #REQUIRED target CDATA #REQUIRED crypted CDATA #REQUIRED os CDATA #IMPLIED> <!ELEMENT install-scripts (install-script*)> <!ELEMENT install-script (data)> <!ATTLIST install-script name CDATA #REQUIRED os CDATA #IMPLIED> <!ELEMENT data (#PCDATA)> <!ELEMENT install-shortcuts (install-shortcut*)> <!ELEMENT install-shortcut (#PCDATA)> <!ATTLIST install-shortcut name CDATA #REQUIRED icon CDATA #REQUIRED source CDATA #REQUIRED args CDATA #REQUIRED destination CDATA #REQUIRED work-dir CDATA #REQUIRED description CDATA #REQUIRED os CDATA #IMPLIED> <!ELEMENT properties (property*)> <!ELEMENT property (#PCDATA)> <!ATTLIST property key CDATA #REQUIRED value CDATA #REQUIRED> ]>

The DOCTYPE field must be filled properly to parse the XML correctly. All fields are explained in detail below:

<!ELEMENT install (product-name, installed-dir, installed-groups,

installed-program-folder)> – this is the root element. It must have the name install.

<!ELEMENT product-name (#PCDATA)> – specifies the valid product name.

<!ELEMENT installed-program-folder (#PCDATA)> – specifies a folder in which the program shortcuts are installed.

<!ELEMENT installed-dir (#PCDATA)> – specifies a folder in which the program is installed.

<!ELEMENT install-groups (install-group*)> – describes which groups are installed.

<!ELEMENT install-group (installed-files, install-scripts, install-

shortcuts, properties)> – describes the properties, files, scripts, and shortcuts of an installed group.

248/309


<!ATTLIST install-group name CDATA #REQUIRED group-dir CDATA #REQUIRED

description CDATA #REQUIRED size CDATA #REQUIRED> – specifies an installed group. group-dir specifies the relative path of a group from the installation directory. description represents a short description of a group. size is the group size in bytes.

The following tags describe internal information, which does not concern the development of third-party tools:

<!ELEMENT install-files (install-file*)> <!ELEMENT install-file (#PCDATA)> <!ATTLIST install-file name CDATA #REQUIRED source CDATA #REQUIRED target CDATA #REQUIRED crypted CDATA #REQUIRED os CDATA #IMPLIED> <!ELEMENT install-scripts (install-script*)> <!ELEMENT install-script (data)> <!ATTLIST install-script name CDATA #REQUIRED os CDATA #IMPLIED> <!ELEMENT data (#PCDATA)> <!ELEMENT install-shortcuts (install-shortcut*)> <!ELEMENT install-shortcut (#PCDATA)> <!ATTLIST install-shortcut name CDATA #REQUIRED icon CDATA #REQUIRED source CDATA #REQUIRED args CDATA #REQUIRED destination CDATA #REQUIRED work-dir CDATA #REQUIRED description CDATA #REQUIRED os CDATA #IMPLIED> <!ELEMENT properties (property*)> <!ELEMENT property (#PCDATA)> <!ATTLIST property key CDATA #REQUIRED value CDATA #REQUIRED>

The example below describes how Install_log.xml file can be used. The SAP J2EE Engine installation generates this file. You can see it in the SAP J2EE Engine program folder after finishing the installation.

Example: <install> <product-name> SAP J2EE Engine 6.20 Cluster </product-name> <installed-program-folder> SAP J2EE Engine 6.20\ </installed-program-folder> <installed-dir> C:\SAP_J2EEngine6.20\ </installed-dir> <install-groups> <install-group group-dir="admin/" name="admin" size="0"> <install-files> </install-files> <install-scripts> <install-script name="admin/go" os="Windows;Unix;Solaris;Netware">

249/309


<data> "%JAVA_HOME% -classpath \".; ./lib/admin.jar; ./lib/j2eeCA.jar; ./lib/inqmyxml.jar;./lib/iiop.jar; ./lib/jndi1.2.jar; ./lib/ejb11.jar; ./lib/iaik_jce_full.jar; ./lib/iaik_ssl.jar; ./lib/iaik_jsse.jar; ./lib/jsse.jar; ./lib/jcert.jar; ./lib/jnet.jar;\" -Dsun.java2d.noddraw=true com.inqmy.services.admin.gui.AdminFrameView $1$ $2$ $3$ $4$ $5$ $6$ $7$ $8$ $9$" </data> </install-script> </install-scripts> <install-shortcuts> <install-shortcut args="" description="" destination="SAP J2EE Engine 6.20\" icon="C:\SAP_J2EEngine6.20\admin\admin.ico" name="Administrator" os="Windows;Unix;Solaris;Netware" source="C:\SAP_J2EEngine6.20\admin\go" work-dir="C:\SAP_J2EEngine6.20\admin"> </install-shortcut> </install-shortcuts> <properties> </properties> </install-group> </install-groups> </install>

uninstall.xml

Uninstallation user interface generates this uninstall.xml file to define the SAP J2EE Engine components that are subject to uninstalling. This XML document must be generated properly from third-party tools to be passed to the batch uninstallation procedure. The uninstall.xml file must have the following structure:

<!DOCTYPE uninstall [ <!ELEMENT uninstall (uninstall-groups)> <!ELEMENT uninstall-groups (uninstall-group*)> <!ELEMENT uninstall-group (#PCDATA)> <!ATTLIST uninstall-group name CDATA #REQUIRED> ]>

The DOCTYPE field must be filled properly to parse the XML correctly. All fields are explained in detail below:

<!ELEMENT uninstall (uninstall-groups)> – this is the root element. It must have the name uninstall.

250/309


<!ELEMENT uninstall-groups (uninstall-group*)> – describes groups to be uninstalled.

<!ELEMENT uninstall-group (#PCDATA)> – describes the group to be uninstalled.

<!ATTLIST uninstall-group name CDATA #REQUIRED> – specifies name of the group to be uninstalled.

The example below describes how the uninstall.xml file can be used. SAP J2EE Engine installation generates this file. You can see it in the SAP J2EE Engine program folder after finishing the installation procedure if the uninstall group was installed.

Example: <uninstall> <uninstall-groups> <uninstall-group name="admin"> </uninstall-group> <uninstall-group name="config tool"> </uninstall-group> <uninstall-group name="deploying"> </uninstall-group> <uninstall-group name="dispatcher"> </uninstall-group> <uninstall-group name="uninstall"> </uninstall-group> <uninstall-group name="tools"> </uninstall-group> <uninstall-group name="server"> </uninstall-group> <uninstall-group name="docs"> </uninstall-group> </uninstall-groups> </uninstall>

251/309


Chapter 6 J2EE Tutorials

• How to Develop Your First JSP

• How to Develop Your First Servlet

• How to Develop Your First EJB

252/309


How to Develop a JavaServer™ Page using JBuilder 5

Overview

This tutorial describes how to create a JavaServer™ Page (JSP) using JBuilder 5 and to develop a simple JSP that multiplies two numbers.

Prerequisites

• Basic knowledge of the JavaServer™ Pages technology. • Basic skills at HTML and Java programming languages. • An installed and running JBuilder 5. • An installed and running J2EE Engine.

253/309


Steps to Create a Simple JSP

Step 1: Create a New Project

Choose File → New Project.

Creating a new project

In the “Project Wizard” dialog that appears specify a new name for the project and specify the desired location of the project. Then choose “Finish.” A new project is created. In the left-hand part of the screen appears a HTML file node.

Step 2: Create New Web Group

Choose File → New → Web → JavaServer Page. Choose “OK”.

254/309


Choose JavaServer Page component

Step 3: Create the JSP File

In the dialog that appears specify the JSP properties. Specify “Simple” as name of the JSP. Choose “Finish”. A new JSP file is created.

255/309


Specify the name of the JSP

Step 4: Enter the JSP Code

Choose “Source” tab from the bottom right-hand panel.

256/309


Simple.jsp Source tab

Use this source code for the JSP file:

<HTML> <BODY> <center> <H2> This JSP Multiplies two Numbers.</H2> <% String action = request.getParameter("ACTION"); float x=0; float y=0; boolean correct=true; if((action!=null)&&(action.equals("MULTIPLY"))){ try{ x = (new loat(request.getParameter("X"))).floatValue(); }catch(Exception e){ correct=false; %><font color="red">Parameter X is not orrect!</font><br><% } try{ y = (new Float(request.getParameter("Y"))).floatValue();

257/309


}catch(Exception e){ correct=false; %><font color="red">Parameter Y is not correct!</font><br><% } if(correct){ float z=x*y; %><h3>The product of <%=x%> and <%=y%> is <%=z%>.</h3><% } %><br><a href="Simple.jsp"><h3>Back</h3></a><% }else{ %> <H3>Enter the numbers.</H3> <FORM ACTION="Simple.jsp" METHOD="GET"> <INPUT TYPE="TEXT" NAME="X" VALUE="0"> * <INPUT TYPE="TEXT" NAME="Y" VALUE="0"> <INPUT TYPE="SUBMIT" NAME="ACTION" VALUE="MULTIPLY"> </FORM> </center> </BODY> </HMTL> <% } %>

Step 5: Add the Required Libraries to the Project

Choose Project → Project Properties… → Path → Required Libraries. Choose “Add”. From the dialog that appears choose “New.” In the new dialog specify “JSP_lib” as name for the library. Choose “Add” and browse to <J2EE_Engine_install_dir>/cluster/server/additional-lib or <J2EE_Engine_install_dir>/alone/additional-lib directory. Choose “OK”.

Step 6: Make the Project

Choose Project → Make Project ”JSP.jpx” from the menu to compile the files.

258/309


Building the project

Note: If you copy the SAPJ2EEEngineJBuilderPlugin.jar from <J2EE_Engine_install_dir>/tools/JbuilderPlugin and paste it in the <JBuilder_install_dir>/lib/ext directory, omit Step 5 from the above procedure.

Deploy the Example

Deploy the JSP on J2EE Engine 6.20. For details refer to the J2EE Engine 6.20 documentation.

Step 1: Start J2EE Engine and Deploy Tool

Start the dispatcher and the server for the cluster version of J2EE Engine 6.20 or alone for the alone installation of J2EE Engine 6.20. Run the Deploy Tool from Start → Programs SAP J2EE Engine 6.20 → Tools → Deploy Tool.

259/309


Step 2: Create New Deployment Project


Open the Deploy Tool. Choose Project → New Project. Choose a name for the project and choose “OK”.

260/309


Step 3: Add Web

Adding Web component

Creating Web Archive Name

Choose J2EEComponents → Add Web. From the dialog that appears activate the “create new component” indicator. Specify “simple_jsp” as name of the web war. Choose “OK”.

261/309


Step 4: Add the JSP

Adding files to the created WAR

From the left-hand part of the screen choose “simple_jsp.war”. In the right-hand part of the screen appears the tab for managing the properties of the JSP file. Choose “File” then the “…” button. In the dialog that appears browse to the location of the compiled JSP file. Choose “OK” then choose “Add File.”

Step 5: Make All

Choose Project → Make All.

Step 6: Make All Archives

Choose J2EEComponets → Make All Archives or the corresponding icon from the menu bar.

262/309


Step 7: Make EAR

In the Assembler tab, choose Assemble → Make EAR or the corresponding icon on the menu bar.

Step 8: Deploy the example

In the Deployer tab choose the created EAR file. Connect to the J2EE Engine. You must be logged in J2EE Engine as user with administrative privileges to be able to deploy the bean on the server. Choose Deploy → Deployment →Deploy EAR or the corresponding icon on the menu bar.

Step 9: Run the JSP

To run the JSP file open a browser and type:

http://localhost/simple_jsp

263/309


How To Develop a Servlet Using JBuilder 5

Introduction

This tutorial describes how to create Servlet using JBuilder 5. The example Servlet used here simply multiplies two numbers.

Prerequisites

• Basic skills at HTML and Java programming language. • Basic knowledge of the Servlet technology. • An installed and running JBuilder 5 full installation. • An installed and running J2EE Engine 6.20.

Steps to Create a Servlet

Step 1: Create a New JBuilder Project

Start JBuilder 5. Choose File → New Project. Specify a name for the project – in this example the name of the project is “Servlet”. Fill in all the required information. Choose “Finish”.

264/309



Step 2: Create a New Web Group

From the menu path choose File → New. In the dialog panel that appears choose the “Web” → “Servlet”.

265/309


Choose Servlet component

Step 3: Creating the Servlet

In this dialog box specify “Simple” as name of the Servlet. Choose “Next” and from the “Generate content type” drop down menu, choose either HTML or SHTML. Choose “Finish”.

Choose servlet name and type

Step 4: Enter the Servlet Source Code

From the left-hand part of the screen select the name of the Servlet. In the text field that appears in the right-hand part of the screen enter the following source code:

package servlet; import javax.servlet.*; import javax.servlet.http.*; import java.io.*; import java.util.*; /** * Title: EJB * Description: Developing a Servlet

266/309


* Copyright: Copyright (c) 2002 * Company: SAP AG * @author SAP AG * @version 1.0 */ public class Simple extends HttpServlet{ public void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { PrintWriter out = response.getWriter(); response.setContentType("text/html ; charset=ISO-8859-1"); out.print("<HTML>\n\t<BODY>\n\t<center>\n\t<H2> This Servlet Multiplies two Numbers.</H2>\n"); String action = request.getParameter("ACTION"); float x=0; float y=0; boolean correct=true; if((action!=null)&&(action.equals("MULTIPLY"))){ try{ x = (new Float(request.getParameter("X"))).floatValue(); }catch(Exception e){ correct=false; out.print("<font color=\"red\">Parameter X is not correct!</font><br>"); } try{ y = (new Float(request.getParameter("Y"))).floatValue(); }catch(Exception e){ correct=false; out.print("<font color=\"red\">Parameter Y is not correct!</font><br>"); } if(correct){ float z=x*y; out.print("<h3>The product of "); out.print(x); out.print(" and "); out.print(y); out.print(" is "); out.print(z); out.print(.”</h3>"); } out.print("<br><a href=\.”./Simple.shtml\"><h3>Back</h3></a>");

267/309


} } }

Source code of the Servlet

Step 5: Enter the HTML Source Code

In the “Servlet.html” subnode, choose the Source tab. Enter the following code:

<HTML> <BODY> <center> <H2> This Servlet Multiplies two Numbers.</H2> <H3>Enter the numbers.</H3> <FORM ACTION=.”/servlet/Simple" METHOD="POST"> <INPUT TYPE="TEXT" NAME="X" VALUE="0"> * <INPUT TYPE="TEXT" NAME="Y" VALUE="0"> <INPUT TYPE="SUBMIT" NAME="ACTION" VALUE="MULTIPLY"> </FORM> </center>

268/309


</BODY> </HTML>

Step 6: Add Libraries

Choose Project → Project Properties… → Path → Required Libraries sub-tab. Use the “Add” button to add library.

Step 7: Using the New Library Wizard

Specify a name for the new library. Choose “New” and browse to the <J2EE_Engine_install_dir>/cluster/server/additional-lib or <J2EE_Engine_install_dir>/alone/additional-lib directory to create the new library required for this example. Choose “OK”.


To compile the project choose Project → Make Project ”Servlet.jpx”.

269/309


Building the project

Step 9: Deploy the Servlet on SAP J2EE Engine.

For details refer to the SAP J2EE Engine documentation.

Note: If you copy the SAPJ2EEEngineJBuilderPlugin.jar from <J2EE_Engine_install_dir>/tools/JbuilderPlugin and paste it in the <JBuilder_install_dir>/lib/ext directory, skip Step 6 and Step 7 from the procedure above.

Deploy the Example

Deploy the Servlet on J2EE Engine 6.20. For details refer to the J2EE Engine 6.20 documentation.

270/309







271/309


Step 3: Add Web

Adding Web component

Creating Web archive name

Choose J2EEComponents → Add Web. From the dialog that appears activate the “Create new component” indicator. Specify “simple_servlet” as name of the web war. Choose “OK”.

272/309


Step 4: Add the Servlet

Adding files to the created WAR file

From the left-hand part of the screen choose “simple_servlet.war”. In the right-hand part of the screen appears the tab for managing the properties of the Servlet file. Choose “File” then the “…” button. In the dialog that appears browse to the location of the compiled Servlet file. Choose “OK”.

273/309


Step 5: Check the Servlet Mapping

Verifying the Servlet mapping

Check the mapping of the Servlet file. It must be WEB-INF/classes/servlet/Simple.class. Choose “Add file”.

274/309


Step 6: Adding the Servlet for Deploy

Adding servlet/jsp component

Choose J2EEComponents → Add Servlet | JSP → Add from files… A dialog with the name of the Servlet appears. Choose “OK”.

275/309


Step 7: Add the HTML File

Adding the HTML file of the servlet

From the left-hand part of the screen select the name of the simple_servlet.war. Select the Files node. Choose the “…” button and browse to the HTML file. Choose “OK”. Choose “Add files”.

Step 8: Make All



Choose J2EEComponets → Make All Archives or the corresponding icon from the menu bar.

276/309


Step 10: Make EAR




Step 12: Run the Servlet

To run the Servlet, open a browser and type:

http://localhost/simple_servlet

277/309


How to Develop a Session Enterprise JavaBean™ using JBuilder 5

Overview

This tutorial describes how to develop a Session EJB using JBuilder 5. The goal is to create a simple session stateless EJB. The development of session stateful EJBs differs insignificantly therefore is not shown.

Prerequisites

• Basic skills at Java programming language. • Basic knowledge of Enterprise JavaBeans technology. • Basic knowledge of the EJB 1.1 Specification. • An installed and running JBuilder 5.

Steps to create a Session Enterprise JavaBean

Step 1: Create a New Project

Start JBuilder 5. From the menu choose File → New Project… Fill in the required information for the project. Name the project “EJBHello”.

278/309



Step 2: Create the EJB Module

Choose File → New → Enterprise → Empty EJB Group. In the dialog that appears specify “EJBHello” as name of the EJB module.

279/309


Choose Empty EJB Group

Step 3: Create the EJB Group

From the menu choose File → New → Enterprise → Enterprise JavaBean. Choose “Next”. Specify “EJBHelloBean” as class name of the bean. Activate the “Stateless session bean” indicator. Choose “Next” and then “Finish”.

Choose Enterprise JavaBean

280/309


Enter the class name of the bean

Step 4: Setting up J2EE Engine 6.20 Plugin

Copy SAPJ2EEEngineJBuilderPlugin.jar from <J2EE_Engine_install_dir>/ tools/JbuilderPlugin and paste it in the <JBuilder_install_dir>/lib/ext directory. Save the project and restart JBuilder 5.

Step 5: Modifying the Tools Properties

From the menu choose Tools → Enterprise Setup… If the plugin is imported properly there is “SAP J2EE Engine 6.20” sub-tab in the “Application Servers” tab.

281/309


Choose Enterprise Setup…

282/309


Choose SAP J2EE Engine 6.20

Step 6: Modifying the Project Properties

From the menu choose Project → Project Properties… → Servers. Activate the “Application server is web server” indicator. Choose the “…” button and from the list that appears select “SAP J2EE Engine 6.20” as application server for the application.

Step 7: Modify the Bean Class

This is the content of the Bean Class:

package ejbhello; import java.rmi.*;

283/309


import javax.ejb.*; /** * Title: EJB * Description: Developing a Session EJB * Copyright: Copyright (c) 2002 * Company: SAP AG * @author SAP AG * @version 1.0 */ public class EJBHelloBean implements SessionBean { private SessionContext sessionContext; public void ejbCreate() { } public void ejbRemove() { } public void ejbActivate() { } public void ejbPassivate() { } public void setSessionContext(SessionContext context) { sessionContext = context; } public String sayHello(String s) throws RemoteException { return "Hello, " + s + "!"; } }

284/309


The source of the EJBHelloBean.java

Step 8: Modify the Remote Interface

This is the source code for the Remote Interface of the EJB:

package ejbhello; import java.rmi.*; import javax.ejb.*; /** * Title: EJB * Description: Developing a Session EJB * Copyright: Copyright (c) 2002 * Company: SAP AG * @author SAP AG * @version 1.0 */ public interface EJBHello extends EJBObject { public String sayHello(String s) throws RemoteException; }

285/309


The source of the remote interface

Step 9: Modify the Home Interface

This is the source code of the Home Interface of the Bean:

package ejbhello; import java.rmi.*; import javax.ejb.*; /** * Title: EJB * Description: Developing a Session EJB * Copyright: Copyright (c) 2002 * Company: SAP AG * @author SAP AG * @version 1.0 */ public interface EJBHelloHome extends EJBHome { public EJBHello create() throws RemoteException, CreateException; }

286/309


The source of the home interface

Step 10: Modify the Deployment Descriptor

To modify the deployment descriptor, select the EJBHello group in the left-hand part of the screen. Double click the name of the first sub-node named “EJBHello”.

Step 11: Add Security Roles

From the Deployment Descriptor sub-nodes choose “Security Roles” and right click it. Choose “New Role”. Specify “All” as name of the role and choose “OK”.

287/309


Choose Security Roles

Enter the name of the new role

Step 12: Add Method Permissions

Choose “Method Permissions” sub-node. Double click it and choose “Add”. Use the drop down menu to specify the method permissions. In this case check the “All” checkbox.

288/309


Specifies different method permissions

Check the “All” checkbox

289/309


Step 13: Add Container Transaction

Use the “Container Transaction” node to specify the container transaction properties. In this case, choose RequiresNew from the “Transaction Attribute” drop down menu.

Specifies container transaction properties

290/309


Set transaction attribute to Requires All

Step 14: Add Data Source

Choose “JDBC 1 Datasources” node to add a new data source. Right click and enter as JNDI name “DataSource.” Specify the properties of the connection to the database server.

Step 15: Modify the Libraries

From the menu choose Project → Project Properties… → Path → Requires Libraries. Choose “New”. Add the .JAR files from the <J2EE_Engine_install_dir>/cluster/server/additional-lib or <J2EE_Engine_install_dir>/alone/additional-lib directory as a new library. Choose “OK”.


Choose Project → Make Project to compile the files.

291/309


Build the project

Step 17: Deploy the EJB to J2EE Engine

Deploy the EJB to J2EE Engine. For information on how to do this refer to the documentation of J2EE Engine.

Deploying the EJBean



292/309



Making a new project


293/309


Step 3: Add Classpath

Choosing the options…

Setting the classpath

294/309


Choose Project → Options… → Classpath. Choose New… → Dir. Browse to the directory, where the classes of your application are located. Choose “OK”. Choose “Add”. Choose “OK”.

Step 4: Add EJB Group

Adding the EJB group

295/309


Creating the JAR file

Choose J2EEComponets → Add EJB Group. Specify “stateless” as name of the .JAR component.

Step 5: Add EJB

Adding a J2EE component

296/309


Loading the ejb-jar.xml file

Choose J2EEComponets → Add EJB. Choose “Load Existing EJB” and browse to the location of the ejb-jar.xml file and the compiled files (class files) of your EJB. Then choose from available beans (in our case EJBHello).

297/309


Step 6: Add Web

Adding a Web component

298/309


Creating the web archive name

Choose J2EEComponets → Add Web. Choose “load existing component” then browse to the web.xml file of the JSP and enter the name of the web archive in the “Web Archive Name” field. In our case it is “hello”.

299/309


Step 7: Add Files to the created WAR

Adding the JSP file

Choose the created WAR file (in our case it is hello.war). Choose “Files” from the “Archive Content Tree” pane and then choose “….” Browse to the directory, where the hello.jsp file is located and then choose “Add File”.

300/309


Step 8: Add the JSP to the created WAR

Adding Servlet/JSP file

Choose J2EEComponets → Add Servlet | JSP → Add from files. Choose “OK”.

Step 9: Make All



In the J2EEComponets tab choose the WAR or the JAR file. Choose J2EEComponets → Make All Archives or the corresponding icon from the menu bar.

Step 11: Make EAR


301/309




Step 13: Run the Example

To run the example, open a browser and type:

http://localhost/hello

302/309


Chapter 7 Appendix

• Message-Driven Bean Deploy Guide

303/309


Message-Driven Bean Deploy Guide

The following deploy guide on Message-Driven EJBean is an example on using MDB. EJB 2.0 is not fully supported in this version of J2EE Engine, so you can use this example (and MDBs at all) only for test and preview purposes. The example is located in <J2EE_Enigne_install_dir>/docs/examples/MDB. This folder contains the following directories:

• classes – the Java classes of the examples. • deploy – the already generated .EAR file, which is ready to be

deployed on the server. • lib – here you must put manually the required library files. • scripts – the running scripts of the example. • src – the source files of the example. • xml – the sources of the .XML files used in the example.

This is the scenario of the example:

A test class sends a message to the queue on which the message-driven bean listens and the MDB on its turn sends a call to a stateless Session Bean for processing, and then prints the result in the server console.

Commands of the Connection Factory

The make_jms_connectionFactory command contains:

factoryName <name of the factory you want to create>

If you use SAP J2EE Engine JMS service or external JMS servers, which supports JNDI, you must use the required type of connection factory. J2EE Engine supports the following connection factories:

• XAQueueConnectionFactory • XATopicConnectionFactory • QueueConnectionFactory • TopicConnectionFactory

This command creates a new JMS ConnectionFactory. The newly generated JMS Connection Factory can be with or without JMS Provider. If the JMS

304/309


Provider is specified then the properties denoted by “*” must be properly specified (for example for SonicMQ JMS Provider.)

o [ - namingEnable <true if JMS Provider provides the Naming Context, false otherwise>

o [* - linkFactoryName <Specifies the name of the remote JMS server factory. Using this name, lookup is performed by the remote Naming system>

o [* - initialContextFactory < INITIAL_CONTEXT_FACTORY of JMS Provider's naming>]

o [* - providerUrl < PROVIDER_URL of JMS provider's naming>]

o [* - securityPrincipal <SECURITY_PRINCIPAL of JMS provider's naming>]

o [* - securityCredentials <SECURITY_CREDENTIALS of JMS provider's naming>]

o [ - objectFactoryName <the name of JMS provider's objectFactory>]

o [ - className <class name of the connection factory>] o [ - propertyName <name of the property for the

connection factory>] o [ - propertyValue < value of the property for the

connection factory>]

The JNDI Context of the factory is: jmsFactories.

Description of the .EJB file

There are two .XML descriptor files in the bean’s jar file.

• Ejb-jar.xml – Standard Deployment descriptor, which Data Type Definition (DTD) you can see in the EJB2.0 Specification

• Inqmy-ejb.xml – Deployment descriptor specific for INQMY EJB2.0 container. It contains the following properties: o Connection-factory-name - The name of the connection factory

that the bean will use. This connection factory must be created using the make_jms_connectionFactory command before the deployment of the bean

o container-size - The initial container size o load-factor - The factor for increasing the container size if it is

necessary

305/309


o property-name and property-value - additional properties that will help the container to get a Connection object from the Messaging System and create a new Session (e.g. you must set clientID property in the xml descriptor if you want the JMS connection to has a client identifier)

Running the example

The easiest way to make JMS Factories command and to deploy an applications that contains Message-Driven Beans (MDB) is to use the .SCR file. The deploy.scr file is script file for the shell. You have to open it with a Text Editor and put this file under a directory of the cluster node of J2EE Engine.

Put the ear in a folder in the server node. For example: jmsExamples\sap_jms\queue\. To deploy the ear in the J2EE Engine server console type:

add deploy

deploy –j2eeVersion 1.3 <full path to the Ear>

This is the content of deploy.scr file:

add ejb20

make_jms_connectionFactory -factoryName myQueueInqmy -

namingEnable true -linkFactoryName QueueConnectionFactory -

initialContextFactory

com.inqmy.services.jndi.InitialContextFactoryImpl -providerUrl

localhost -securityPrincipal Administrator -securityCredentials

add deploy

deploy -j2eeVersion 1.3 .\jmsExamples\sap_jms\queue\message.ear

306/309


Running the Connection Factory using SonicMQ as JMS Provider

To run Connection Factory using SonicMQ as JMS Provider the command must be used in the following way:

add ejb20 make_jms_connectionFactory -factoryName Case1QueueSonicFactory -namingEnable false -objectFactoryName progress.message.jclient.AdministeredObjectFactory -className progress.message.jclient.xa.XAQueueConnectionFactory -propertyName brokerURL propertyValue localhost:2506 propertyName defaultUserName propertyValue admin propertyName defaultPassword propertyValue admin

The following additional settings are required:

Put the client.jar file for the SonicMQ JMS Provider in:

• <J2EEEngine_install_dir>/cluster/server/additional-lib – for cluster installation.

• <J2EEEngine_install_dir>/alone/additional-lib – for standalone installation.

In the library.TXT file located in <J2EEEngine_install_dir>/cluster/server/managers or <J2EEEngine_install_dir>/alone/managers add the following line :

library sonic client.jar … reference sonic jms

In EJB Service properties file located in <J2EEEngine_install_dir>/cluster/server/services/ejb20/provider.xml or <J2EEEngine_install_dir>/alone/services/ejb20/provider.xml add the following tag:

<reference type="library" strength="weak"> sonic

</reference>

307/309


To start EJB20 Service automatically edit the runtime.xml.

<startup-mode> # must be set to “always” manual

</startup-mode>

Start service ejb20.

Sending Messages Between Application and External JMS Server

To send messages between application and external JMS server, (other then J2EE Engine), you have to add the following additional references to the JMS libraries of the application in the reference.txt file located in <J2EEEngine_install_dir>cluster/server/managers/.

SampleApplication library:sonic.

“sonic” is the name of the library defined in library.txt.

See also:

• Administration Manual → Configuration of Additional Libraries

Steps to Run the Example

These are the steps to run the example:

• Adjust the path of the ear file to be deployed in dep.scr • Include the following libraries in the .\lib directory. You must include

the following .JAR files for cluster installation: o <J2EE_Engine_install_dir>cluster/server/additional-lib/jms.jar o <J2EE_Engine_install_dir>cluster/server/additional-lib/ejb20.jar o <J2EE_Engine_install_dir>/tools/lib/client.jar

For standalone version include the following libraries:

o <J2EE_Engine_install_dir>alone/additional-lib/jms.jar o <J2EE_Engine_install_dir>alone/additional-lib/ejb20.jar o <J2EE_Engine_install_dir>/tools/lib/client.jar

• Run the scripts

308/309


To execute the scripts proceed with the following steps:

• Copy the *.scr files to J2EE Engine installation directory. If you use Standalone version, take the files from the ./standalone directory, otherwise take them from ./cluster directory. The following scripts are provided: o all.scr – runs all the other scripts. o dep.scr – deploys the MDB .EAR file. o factory.scr – starts the command, which creates the required

connection factories. o serv.scr – starts the EJB service.

• Make sure the server is started (as well as the dispatcher for cluster installation).

• Type in the server console: run <name of the script>

Example :

> run serv

> run factory

> run dep

309/309

dev manual

Documents