Development Manual - archive.sap.com

SAP J2EE Engine 6.20

Development Manual

Development Manual SAP J2EE Engine 6.20

2/271

Contents

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

J2EE Guide ................................................................................................... 10 J2EE Architecture........................................................................................ 11

J2EE Components .................................................................................. 11 J2EE Containers ..................................................................................... 12 J2EE Clients........................................................................................... 14 J2EE Services......................................................................................... 15

J2EE Application Overview........................................................................... 16 J2EE Application Components.................................................................. 16 J2EE Application Structure ...................................................................... 17 Development Roles ................................................................................ 19 J2EE Applications Development Phases .................................................... 20

Enterprise JavaBeans .................................................................................. 24 Introduction to Enterprise Beans ............................................................. 24 SAP J2EE Engine Enterprise JavaBeans Architecture .................................. 25

Web Components ....................................................................................... 27 Overview............................................................................................... 27 Web Component Roles ........................................................................... 27 Web Component Lifecycle....................................................................... 28 Servlets................................................................................................. 29 JavaServer Pages ................................................................................... 32

Web Services ............................................................................................... 38 Introduction to Web Services ....................................................................... 39

SOAP .................................................................................................... 39 WSDL.................................................................................................... 39 UDDI .................................................................................................... 39

Overview of the Web Services Toolkit ........................................................... 40 Features .................................................................................................... 41 Setting up the Web Service Framework......................................................... 42 Enabling and Disabling SOAP Support ........................................................... 43


3/271

Server Side – Service Endpoints ................................................................... 44 Session Beans........................................................................................ 44

Client Side – Accessing Services ................................................................... 49 SAP J2EE Engine SOAP Proxy Generator................................................... 49

UDDI4J Pluggability .................................................................................... 51 WSIL Integration ........................................................................................ 52 Data Marshalers.......................................................................................... 53 Examples ................................................................................................... 56

Example 1 – Calculator ........................................................................... 56 Example 2 – Simple................................................................................ 57 Example 3 – Complex1 ........................................................................... 57 Example 4 – Complex2 ........................................................................... 58 Example 5 – EchoServlet ........................................................................ 58 Example 6 – UDDI4J .............................................................................. 59

References ................................................................................................. 60 SAP XML Toolkit for Java............................................................................. 61

Basic Concepts ........................................................................................... 62 XSL Overview ........................................................................................ 62 XSL Stylesheet Processing....................................................................... 62 JAXP Overview....................................................................................... 62 XML Schema Validator ............................................................................ 63 Schema to Java Generator ...................................................................... 64

Java API for XML Parsing (JAXP) .................................................................. 65 Introduction to DOM............................................................................... 65 Introduction to SAX................................................................................ 71 XSL Transformations .............................................................................. 75

Advanced Techniques.................................................................................. 79 Integration of XSL with Other Languages ................................................. 79 Multiple Output Documents..................................................................... 81 Active XML Scanning .............................................................................. 83 Evaluating XPath Queries on DOM Objects ............................................... 83 Changing the Default Parser.................................................................... 83

SAP XML Toolkit for Java FAQ ...................................................................... 85 Frequently Asked Questions (FAQ)........................................................... 85

References ................................................................................................. 87 J2EE Examples............................................................................................. 88

Market Summary ........................................................................................ 89


4/271

Market Summary.................................................................................... 89 Application Design.................................................................................. 89 JavaServer Page – YahooFinanceRetriever.jsp .......................................... 90 JavaBean – FacadeBean.java .................................................................. 92 Container-Managed Entity Bean............................................................... 93 Stateless Session Bean ........................................................................... 93 Core Java Class – YahooFinanceWebContent.java ..................................... 94 Deployment Specifics of MarketSummary Example .................................... 94

CD Collection............................................................................................ 103 Overview............................................................................................. 103 Application Components ....................................................................... 103 Application Design and Development ..................................................... 104

Statistical Calculator.................................................................................. 107 Overview............................................................................................. 107 Application Components ....................................................................... 107 Application Design and Development ..................................................... 107

Developers Tasks....................................................................................... 113 Configuring JBuilder Plug-in for Application Deployment and Debugging ........ 114

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

Lookup Resources over the JNDI................................................................ 123 Services Lookup................................................................................... 123 Binding Local and Global Objects. Persistent and Non-Persistent Statute ... 124 Lookup from a Different Cluster............................................................. 125

Services Guide ........................................................................................... 127 Overview.................................................................................................. 128 Admin Service .......................................................................................... 129

Overview............................................................................................. 129 Interfaces............................................................................................ 129 Example .............................................................................................. 133

Appclient Service ...................................................................................... 135 Overview............................................................................................. 135


5/271

Interfaces............................................................................................ 135 Example .............................................................................................. 138

DBMS Service ........................................................................................... 140 Overview............................................................................................. 140 Interfaces............................................................................................ 140

DBPool Service ......................................................................................... 141 Overview............................................................................................. 141 Interfaces............................................................................................ 141 Example .............................................................................................. 147

Deploy Service.......................................................................................... 149 Overview............................................................................................. 149 Interfaces............................................................................................ 149 Example .............................................................................................. 155

EISConnector Service ................................................................................ 157 Overview............................................................................................. 157 Interfaces............................................................................................ 157 Example .............................................................................................. 158

EJB1.1 Service.......................................................................................... 159 Overview............................................................................................. 159

EJB2.0 Service.......................................................................................... 161 Overview............................................................................................. 161 Description of inqmy-ejb.xml................................................................. 161

File Service............................................................................................... 167 Overview............................................................................................. 167 Interfaces............................................................................................ 167 Example .............................................................................................. 170

HTTP Service............................................................................................ 171 Overview............................................................................................. 171 Interfaces............................................................................................ 171 Example .............................................................................................. 172

HTTP Tunneling Service ............................................................................ 173 Overview............................................................................................. 173 Example .............................................................................................. 173

IIOP Service ............................................................................................. 174 Overview............................................................................................. 174 Interfaces............................................................................................ 175

JavaMail Service ....................................................................................... 176


6/271

Overview............................................................................................. 176 Client View .......................................................................................... 176

JMS Service.............................................................................................. 177 Overview............................................................................................. 177 Developing a JMS Client........................................................................ 178 Interfaces............................................................................................ 179 Example .............................................................................................. 182

Keystore Service ....................................................................................... 184 Overview............................................................................................. 184 Interfaces............................................................................................ 184

Log Service .............................................................................................. 185 Overview............................................................................................. 185 Interfaces............................................................................................ 185

Naming Service......................................................................................... 189 Overview............................................................................................. 189 Interfaces............................................................................................ 189

P4 Service ................................................................................................ 191 Overview............................................................................................. 191 Interfaces............................................................................................ 192 Example .............................................................................................. 193

RFC Engine Service ................................................................................... 195 Overview............................................................................................. 195 Interfaces............................................................................................ 195

Security Service ........................................................................................ 196 Overview............................................................................................. 196 Interfaces............................................................................................ 196 Example .............................................................................................. 219

Servlets_jsp Service .................................................................................. 223 Overview............................................................................................. 223 Interfaces............................................................................................ 223 Example .............................................................................................. 223

Shell Service............................................................................................. 224 Overview............................................................................................. 224 Interfaces............................................................................................ 224

SSL Service .............................................................................................. 227 Overview............................................................................................. 227 Interfaces............................................................................................ 228


7/271

Telnet Service........................................................................................... 229 Overview............................................................................................. 229 Interfaces............................................................................................ 229

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

Developing Third-Party Visualizations of SAP J2EE Engine Tools ............. 236 Overview.................................................................................................. 237 Config Tool............................................................................................... 238

batchconfig.xml ................................................................................... 238 SAP J2EE Engine Installation and Uninstallation Programs ............................ 242

Manifest.xml ........................................................................................ 243 BatchSetup.xml.................................................................................... 246 install_log.xml...................................................................................... 249 uninstall.xml ........................................................................................ 251

Message-Driven Bean Example ................................................................. 253 Overview.................................................................................................. 254

About the Example............................................................................... 254 Running the Example ........................................................................... 255 Running the Connection Factory using SonicMQ as JMS Provider .............. 257 Sending Messages Between Application and External JMS Server ............. 258

IqLib, Introduction to SAP Java Data Structures and Algorithms Library 259 Overview.................................................................................................. 260

Features.............................................................................................. 260 Benefits of Using IqLib.......................................................................... 260 Goals .................................................................................................. 261

Introduction ............................................................................................. 262 Packages............................................................................................. 262 Key Concepts....................................................................................... 262 Data Structures.................................................................................... 263 Iterators.............................................................................................. 266 Algorithms........................................................................................... 267 Multithreading and Synchronization ....................................................... 268


8/271

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™ 2.2, and Enterprise JavaBeans Specification™ 1.1.

Web Services

Contains a description of the Web Services technology, some examples, and references.

SAP XML Toolkit for Java

Describes the functionality of the SAP J2EE Engine XML Toolkit, provides a set of basic examples and answers to some frequently asked questions.

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.

Developers Tasks

Contains the description of some specific developers tasks.


9/271

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.

IqLib

An introduction to the SAP Java data structures and algorithms library.

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 • Deployment Manual


10/271

Chapter 1 J2EE Guide

• J2EE Architecture

• J2EE Application Overview

• Enterprise JavaBeans

• Web Components


11/271

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

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.


12/271

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)

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 Engine – 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.


13/271

• 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 EJB container manages the execution of all enterprise beans in one J2EE application. Enterprise beans 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.


14/271

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


15/271

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™


16/271

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


17/271

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.

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:


18/271

• 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 deployment descriptors – XML files used for setting up the component properties.

An EJB component contains:

• A bean class • Two interfaces (home and remote) • Deployment descriptors, which provides information about the composition

and structure of the application • Optionally, helper classes, on which the enterprise bean depends


19/271

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.

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


20/271

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

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


21/271

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:

• 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


22/271

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

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 client JAR file

Deliverable: the JAR file containing the J2EE application client


23/271

J2EE Application Client Creation

J2EE Application Assembling


Tasks:

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

• Specifies the deployment descriptor for the J2EE application

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


24/271

Enterprise JavaBeans

Introduction to Enterprise Beans

SAP J2EE Engine implements the Enterprise JavaBeans™ 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, the enterprise beans 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. Enterprise beans can interoperate with non-Java programming language applications and are compatible with the CORBA protocols.

EJB1.1 and EJB2.0

SAP J2EE Engine 6.20 fully supports Enterprise JavaBeans™ Specification, v1.1 from Sun™ Microsystems and partly implements the features of Enterprise JavaBeans™ Specification, v2.0. As the EJB 2.0 implementation is only a prerelease in this version of the SAP J2EE Engine, we do not recommend using it in productive systems but only for test scenarios. The EJB 2.0 implementation is expected to change in future releases of SAP J2EE Engine.

Types of Enterprise Beans

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 database – that is, they survive server crashes. Entity beans can have bean-managed or container-managed persistence.


25/271

SAP J2EE Engine Enterprise JavaBeans Architecture

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

SAP J2EE Engine

SAP J2EE Engine EJB Container

Client

Deployment Descriptor

BeanInstancesBean

InstancesBeanInstances

Session or Entity Bean

EJBObjectsEJBObjects

EJBObjects

EJBHome

Enterprise JavaBeans Architecture

The SAP J2EE Engine EJB container:

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

container • Manages the client access to the enterprise beans deployed on the SAP J2EE

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

• Manages the transactions, security, and exceptions • Provides the deployed enterprise beans with network distribution of clients

and scalable management of resources • Generates the EJBObjects and the Home Objects classes

The client view of the EJB components is presented by:

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

Structure

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


26/271

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 bean’s 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 bean’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 enterprise bean and its elements in an XML file.


27/271

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.

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


28/271

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


29/271

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

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


30/271

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

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


31/271

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.

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


32/271

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:

• 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 a 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


33/271

parameters to a bean component. The JSP file can then query the bean to obtain the results of the computation.

JSP Request Model

Some example bean components that can be used within a JavaServer Pages file are a JDBC or enterprise beans. 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.


34/271

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 %>

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.


35/271

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


36/271

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 %>

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.


37/271

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 enterprise bean 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 programming. This is the programming model supported by the Java 2 Platform Enterprise Edition (J2EE).

N-tier Model


38/271

Chapter 2 Web Services

• Introduction to Web Services

• Overview of the Web Services Toolkit

• Features

• Setting up the Web Service Framework

• Enabling and Disabling SOAP Support

• Server Side – Service Endpoints

• Client Side- Accessing Services

• UDDI4J Pluggability

• WSIL Integration

• Data Marshalers

• Examples

• References


39/271

Introduction to Web Services

The growing need of fast, secure and efficient bussines-to-bussines communications imposes Web Services as a main technology. Web services are offered via the Internet as they use an XML-based communication protocol (SOAP).

The interaction between Web Services and business applications is simple and productive. The application sends a request to a service at a specified URL. The request is then processed by the service and the response is sent back to the application. A short résumé of additional technologies related to Web Services is given below.

For more information about this topic and the matters presented below, see the drafts released by the W3C organization.

SOAP

SOAP (Simple Object Access Protocol) is an XML-based protocol, which is developed to allow network communication between different applications via the World Wide Web. Its language and platform independence along with the opportunity to run over HTTP, make it an excellent choice for exchanging information over the Internet.

WSDL

WSDL (Web Service Description Language) is the primary means for describing Web Services. It is based on XML and is used to define Web Services. In addition the WSDL describes the operations (methods) that the particular Web Service exposes and how and where to access them.

UDDI

UDDI (Universal Description, Discovery and Integration) is a new technology that allows services and businesses to be published in the Internet. These services (or businesses) are stored in UDDI repositories and can be accessed through a particular client (web browser).


40/271

Overview of the Web Services Toolkit

The Web services toolkit provides a framework for handling the emerging Web service issues. Using the new features and tools one can easily use Web service technologies either on the client or on the server sides. This document will provide information for the following topics:

• Overview of the supported by the framework features • Setting up the SAP J2EE Engine • Using Enterprise Java Beans as Web service endpoints • Configuration of a Web service • Client side proxy generation

For more detailed information about Web services concepts and technologies refer to JSR 109.


41/271

Features

Here is an outline of the standards supported by the framework.

• Full implementation of Sun’s Java XML Pack Winter 01 o JAXP 1.2 o JAXM 1.0 o JAX-RPC 0.6

• Any session bean as Web service • SOAP headers on client and server side • Configurable WSDL generation on server side • Proxy generation on client side • UDDI4J pluggability • SOAP 1.1 + attachments support • Web Services Inspection Language (WSIL)


42/271

Setting up the Web Service Framework

In order to access the Web service framework, enter http://localhost/soapdispatcher in your browser.


43/271

Enabling and Disabling SOAP Support

You can enable and disable the SOAP Support for SAP J2EE Engine through the global-web.xml file located in <SAPj2eeEngine_install_dir>/cluster/server/services/servlet_jsp or <SAPj2eeEngine_install_dir>/alone/services/servlet_jsp directory. By default the SOAP Support is enabled. To disable it, remove or put in comments the following tags from the global-web.xml file:

<servlet> <servlet-name>soapdispatcher</servlet-name> <servlet-class>com.inqmy.services.servlets_jsp.server.SoapServlet</servlet-class> </servlet>

and

<servlet-mapping> <servlet-name>soapdispatcher</servlet-name> <url-pattern>/soapdispatcher/*</url-pattern> </servlet-mapping>

In order for the changes to take effect, restart the J2EE Engine.

Add the above tags in the global-web.xml file in order to activate the SOAP Support. In this case a restart of the J2EE Engine is also required.

This must be done for each application node.


44/271

Server Side – Service Endpoints

Session Beans

General

Session beans are the preferred kind of J2EE component for an implementation of a Web service. Using the Web service framework, any session bean can be easily transformed into a Web service (and for simple ones you will not have to write a line of code).

To expose a bean as a Web service, it must be deployed.

Using the Web service framework you can use any existing session bean as a Web service. After deploying it, you just have to go to http://localhost/soapdispatcher, and browse through the deployed beans until you find the right one. Clicking on it will generate a WSDL, which can be used to access that bean. Another way of getting the WSDL is by loading directly: http://localhost/soapdispatcher?WSDL=<beanName>. For example: http://localhost/soapdispatcher?WSDL=Calc, for a bean named “Calc”.

In order to access a particular bean you can use the generated proxy from the bean’s WSDL. The generation of the proxy is executed by the Proxy Generator. For more information, see “SAP J2EE Engine SOAP Proxy Generator” section.

By default the framework can automatically handle the following types:

• All Java simple types - byte, short, int, long, char, float, double, boolean, along with their wrapper classes - Byte, Short, Integer, Long, Character, Float, Double, Boolean.

• java.lang.String • Arrays of any value and dimension • Java Bean Styled objects – These are classes, which only meaningful

parameters are either public variables, or get() or set() methods. By default this is used to handle all kinds of special objects, which do not have any DataMarshaller associated.

• For all kinds of classes, which do not fall into these categories, there is a DataMarshalling framework, which allows serialization or deserialization and correct WSDL generation for any user class, by providing user DataMarshallers. This topic will be covered later.

WSDL Generation

The rules for generation of WSDL definitions of a bean follow the concepts lined out in the JAX-RPC specification. If the default naming is not correct for some application there is a way to change the behavior of the WSDL generator. A list of the rules used to generate the names of the elements in the WSDL definitions is provided below. The default rules can be overloaded by an entry in the MarshalDescriptor.xml. This will be covered next.

In the following description MD:<xxx> means – the content of the tag <xxx> in the MarshalDesctiptor.


45/271

• AppName := <ApplicationName> | MD:<soap-name>. • When the Schema for complex types is generated, each complex type has

either the classname of the type, or a mapping specified in the MarshalDescriptor – <name-mapping> tags for each bean.

• MessageNames o MethodMessages := AppName + <MethodName> + “_” + (“Request” |

“Response”) • PartName := (“P” + <ParameterIndex>) | MD:<param>.

o Header Messages := <MethodName> + (“_RequestHeaders” | “_ResponseHeaders”) The names of the “part” elements are the names of the headers, and their type is the type of the header.

o ExceptionMessages := <ExceptionName> + “Message” ExceptionMessages have only one part named “errorMessage”, of type “xs:string”.

• PortTypeName := AppName + “Interface” o Operation.Name := <MethodName> o Operation.Input := <MethodName> + “Request” o Operation.Output := <MethodName> + “Response” o Operation.Fault := <ExceptionName>, the type is the type of the

specified exception message. Each exception has a specific message. • BindingName := AppName + “SOAPHTTPBinding” • Headers – If the method needs to have some Request or Response header

entries in the definition. You must use the MarshalDescription.xml.

Marshal Description

This is an XML file, used to specify additional configuration needed for generation of the WSDL or runtime of a Web service. It must be located in the root directory of exactly one JAR inside an EAR, and is valid for all the beans in the application. It must be named “MarshalDescription.xml”. This is the Schema definition of this XML file:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="marshal-descriptor" type="marshalDescriptorType"/> <xs:complexType name="marshalDescriptorType"> <xs:sequence> <xs:element name="bean" type="beanType" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="data-marshaler" type="dataMarshalerType" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> <xs:complexType name="beanType"> <xs:sequence> <xs:element name="soap-name" type="xs:string" minOccurs="0"/> <xs:element name="method-descriptor" type="methodType" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="name-mapping" type="extensibleClassNameMappingType" minOccurs="0" maxOccurs="unbounded" /> </xs:sequence> <xs:attribute name="name" type="xs:string" use="required"/> <xs:attribute name="class" type="xs:string" use="required"/>


46/271

</xs:complexType> <xs:complexType name="methodType"> <xs:sequence> <xs:element name="soapAction" type="xs:string" minOccurs="0"/> <xs:element name="request-header" type="methodHeaderType" minOccures="0" maxOccurs="unbounded"/> <xs:element name="response-header" type="methodHeaderType" minOccures="0" maxOccurs="unbounded"/> <xs:element name="param" type="paramType" maxOccurs="unbounded" minOccurs='1'/> </xs:sequence> <xs:attribute name="method" type="xs:string" use="required"/> </xs:complexType> <xs:complexType name="methodHeaderType"> <xs:all> <xs:element name="header-name" type="xs:string"/> <xs:element name="header-type" type="xs:string"/> </xs:all> <xs:attribute name="isRequired" type="xs:boolean"/> </xs:complexType> <xs:complexType name="paramType"> <xs:attribute name="name" type="xs:string" use="required"/> <xs:attribute name="type" type="xs:string" use="required"/> </xs:complexType> <xs:complexType name="extensibleClassNameMappingType"> <xs:all> <xs:element name="java-name" type="xs:string"/> <xs:element name="wsdl-name" type="xs:string"/> </xs:all> </xs:complexType> <xs:complexType name="dataMarshalerType"> <xs:all> <xs:element name="create-method" type="xs:string"/> <xs:element name="marshaler-classname" type="xs:string"/> <xs:element name="marshaled-class" type="xs:string"/> </xs:all> </xs:complexType> </xs:schema>

Each Marshal descriptor starts with a <marshal-desriptor> tag. Then several <bean> and several <data-marshaler> tags might follow.

<bean> - describes one specific bean of the application. To specify the bean, both the “name” and “class” attributes must be supplied. The “class” specifies the RemoteInterface class. There are three types of descendant elements <soap-name>, <method-descriptor> and <type-mapping>.

<soap-name> - specifies the name, which will be used when generating the WSDL, instead of the name of the bean. If the bean is “ExampleBean”, and you want in the WSDL, ExampleWebService to be displayed, you should use this tag.


47/271

<method-descriptor> - this element allows you to specify additional options for each method. These include - <request-header>, <response-header> and <param>. The method name is specified by the “method” attribute.

<request-header> - each element specifies a header, which is required or allowed in the SOAP request. Using the “isRequired” attribute you might specify, whether to set the required attribute on the soap:header or not. Further you should set the <header-name> and <header-type> elements. Currently only headers of type String and int are supported.

<response-header> - similarly to the <request-header> element. This element specifies headers, which could be returned by the service.

<param> - each of these tags specifies a mapping for the name of a method parameter. Since there is no way to take the names of the parameters using Java Reflection, by default their names are mapped like “p0”, “p1”, … and so on. If you would like to perform an overload, you have to specify a <param> element for each of the parameters in the method signature, in the correct order. The <param> element has two descendants – the new name, and the Java type of the parameter. The Java type is required in order to distinguish the methods when there are overloaded methods.

<name-mapping> - this element is used to overload the default naming of complex types generated in the <definition> element of the WSDL. By default, when the WSDL generator encounters some complex Java type, it creates a complex Schema type, which name is the class name of the Java type. If the WSDL needs to be independent of the implementation, you must use a name mapping.

Soap Headers – Server Side

A short explanation of how to design your session bean to use SOAP headers will be presented. Later in the topic will be explained how to use the generated proxy to set Request, or get Response headers.

To enable your bean to receive or send SOAP headers along with the Response, you must perform three tasks:

• RemoteInterface – Instead of extending EJBObject, you have to extend com.inqmy.lib.soap.headers.SOAPHeadersInterface. The latter on the other hand should extend EJBObject.

• Session bean class – Instead of implementing SessionBean, you have to implement com.inqmy.lib.soap.headers.SOAPSessionBean

• <SAPj2eeEngine_install_dir>/alone/managers/reference.txt or <SAPj2eeEngine_install_dir>/cluster/server/managers/reference.txt – you will have to add the following entry to this configuration file: o reference <appName> library:inqmyxml

The bean implementation, which extends SOAPSessionBean, includes the following methods, derived from SOAPSessionBean:

• public Hashtable getRequestHeaders() throws RemoteException • public Hashtable getResponseHeaders() throws RemoteException • public Object getRequestHeader(String name) throws

RemoteException


48/271

• public Object getResponseHeader(String name) throws RemoteException

• public void setRequestHeader(String name, Object value) throws RemoteException

• public void setResponseHeader(String name, Object value) throws RemoteException

Using them you can access the headers, and get or set them.

Soap Faults

Since there is no standard way to specify the fault:actor, fault:code, fault:string and fault:detail using WSDL, there is a special kind of exception, which you might throw in your methods – com.inqmy.lib.jaxm.soap.SOAPFaultException. When the SOAPDispatcher catches such an exception, it reads the special fields, and generates a proper soap:fault response. Then in the generated proxy, you might catch this exception (it is the same class) and check the proper fields. The available constructors are:

• public SOAPFaultException(String fcode, String factor, String fstring, String fdetail, Throwable t);

• public SOAPFaultException(String fcode, String factor, String fstring, String fdetail);


49/271

Client Side – Accessing Services

Proxy Generator provides an easy way to access a Web service using the Web services toolkit.

SAP J2EE Engine SOAP Proxy Generator

Usage

This is the first, and currently the most reliable way to use proxies on the client side. There are a number of options, which allow you to customize the SOAP request, for a specific server. There is also a way to handle SOAP headers in the SOAPRequest and SOAPResponse.

Invoking a proxy method generates a SOAP message, which is sent to the server. The SOAP message is processed and the bean’s method is invoked. The result, which the server returns is again a SOAP message, which is then processed by the client. This SOAP message contains the result of the bean's method invocation on the server side.

If you want to access the bean, the proxy from the bean’s WSDL must be generated. The Proxy Generator handles this task.

The class of the Proxy Generator is com.inqmy.lib.wsdl.ProxyGenerator. It is located in <SAPj2eeEngine_install_dir>/cluster/server/additional-lib/inqmysoap.jar or <SAPj2eeEngine_install_dir>/alone/additional-lib/inqmysoap.jar file. In addition the following JAR files must be included in your classpath - mail.jar, activation.jar, inqmyxml.jar, inqmysoap.jar, located in <SAPj2eeEngine_install_dir>/cluster/server/additional-lib/ or <SAPj2eeEngine_install_dir>/alone/additional-lib/ directory. You need also the inqmy-lib.jar file in <SAPj2eeEngine_install_dir>/cluster/server/lib/ or <SAPj2eeEngine_install_dir>/alone/lib/ directory in order to run the generator. An example clarifying these issues is given below:

java –cp <absolute_jarfiles_path> com.inqmy.lib.wsdl.ProxyGenerator <wsdl_file> <proxy_output_directory> [options]

where:

• <absolute_jarfiles_path> - specifies the full path the required JAR files. • <wsdl_file> - the WSDL file, for which a proxy will be generated. • <proxy_output_directory> - the directory where the proxy files will be

generated.

A list of the available options follows:

• [-p package] – name of the package. • [-c] – compile the generated files. • [-j jarname] – creates JAR file with the specified jarname and includes the

compiled proxy files in it. • [-d] – creates RPC methods for document style Webservices.


50/271

• [-x filename.txt] – protects names in filename.txt from overwriting (writes a single name on a row).

Generated Stuff

• wsdl:service – for the wsdl:service tag a class is generated, having the same name as the “name” attribute of the service tag. This class has a method: public com.inqmy.lib.wsdl.base.ProxyPortBaseSOAP getPort(String name) which returns the port associated with this name. The returned class has to be cast to the port class. For example Calc calcPort = (Calc)calcService.getPort(“Calc”);

• wsdl:port – for each port in the service a class is generated, which has the same name as it is in the “name” attribute of the wsdl:port tag.

• wsdl:operation – for each operation of this port, a method in the port class is generated having the same name and signature as described in the input and output messages. Later in this document the mapping between Schema types and Java types will be described.


51/271

UDDI4J Pluggability

The SAP J2EE Engine Web services framework can be also plugged as a transport protocol into the IBM UDDI4J implementation. In order to perform this task, you must set as system property the following:

org.uddi4j.TransportClassName=com.inqmy.lib.soap.uddi4j.InQMySOAPTransport (for UDDI4J v2)

and include the following classes in your classpath:

• Web services framework o inqmyxml.jar o inqmysoap.jar

• HTTPS support (Required by the Publish API) o jsse.jar o jnet.jar

• Generic libraries o activation.jar o mail.jar o jaxm.jar


52/271

WSIL Integration

Web Services Inspection Language (WSIL) is an XML-based protocol, which allows inspecting the Web services hosted by a server. The WSIL port of the SAP J2EE Engine is: http://<server-addr>/soapdispatcher/inspection.wsil.


53/271

Data Marshalers

Let’s consider the following example of a class and a method, using this class:

public class A implements Serializable { private int b; public int getB() { return b; } public void setB(int b) { this.b = b; } }

-- and in the bean the following method is included:

public String readA(A a);

There is no way for the framework to be informed exactly which methods to call in order to set the variable b, and give an instance of the class A to the method. In this case DataMarshaler is used.

Introduction to Data Marshalers

The idea is that using a DataMarshaler and a MarshalDescription.xml (which associates the DataMarshaler classes with user classes), the framework can easily find out what kind of data should be transferred in order to get all the information from a user object. The DataMarshaler also cares for instantiating new objects using the data received, and using an object, to return a list of DataFields, which describe the object. The DataMarshaler is also used during the generation of the WSDL definition of the bean. For each user class, a DataMarshaler is searched and after that the getDataFieldList() method is invoked to see what DataFields are needed by this DataMarshaler. Then these fields are recursively described in the WSDL. In this way you only need to write a simple class specifying what kind DataFields you wish to expose and then using this DataFields, to return an instance, or using an instance to return the fields.

Note: If your application uses Data Marshalers you must add in the <SAPj2eeEngine_install_dir>/alone/managers/reference.txt or <SAPj2eeEngine_install_dir>/cluster/server/managers/reference.txt an entry in the form: reference <app_name> library:webservices

Usage

In order to support such user classes several classes and interfaces are defined.


54/271

A is a class, which knows exactly what data is needed in order to produce DataMarshaler instance of a specific class. Also with a specified instance – what fields to expose. The Marshaling framework uses DataFieldList objects to hold the data. A DataFieldList object consists of several DataField objects. The DataField object holds information for exactly one data field of the class. It has a name, a dataClass, and a value – an instance of the data class.

Usage of the methods of DataMarshaler class is explained below:

• DataFieldList getDataFieldList() – this method must return a DataFieldList, which consists of the DataFields the user wants to expose. Only the name and the dataClass should be initialized – this method is used, when generating the WSDL of the service in order to describe what kind of objects must be supplied to the framework.

• Object unmarshal(DataFieldList, SOAPContext) – this method is used when the framework needs to create an instance of a user class and use it. The framework provides a fully initialized DataFieldList object, which has the same DataFields in the same order as they were provided by the getDataFieldList() method. Now the objects carried by the DataFields are actually instances. The user must use these objects to create an instance of the marshaled class, and return it to the framework.

• DataFieldList marshal(Object data, SOAPContext) – this method is invoked by the framework, when a user object needs to be converted to XML data. The user must use the provided Object and return a DataFieldList, with DataFields of type and order exactly as returned by the getDataFieldList() method.

Now you must include this class to your bean, and create a MarshalDescription.xml file, in the root directory of the bean’s JAR file. If your application has several beans,

getDataFieldList() : DataFieldListunmarshal(DataFieldList, SOAPContext) : Objectmarshal(Object, SOAPContext) : DataFieldList

DataMarshaler

DataFieldList(String className)add(DataField)add(int index, DataField)item(int index) : DataFieldremove(int index)size() : intclear()

DataFieldList

DataField(String name, Class dataClass)DataField(String name, Class dataClass, boolean isUbounded)reuse(String name, Class dataClass)reuse(String name, Class dataClass, boolean isUbounded)reuse(Object data)getName() : StringgetDataClass() : ClassgetData() : Objectubounded() : boolean

name : StringdataClass : Classdata : ObjectisUnbounded : boolean

DataField1

*


55/271

this file must be in exactly one JAR. It describes what DataMarshalers are provided by the user and for which classes.

The MarshalDescription.xml can also include additional information about the WSDL generation. The tag <bean name=”xxx”>, where xxx is the name of the bean, and his descendants <soapname> and <method–descriptor class=”xxx” method=”yyy”> contain this information. Neither of them is required. If any of them is omitted, the standard way of creating names (according to JSR-109) is used. The <soapname> encloses the name, which you want to be used instead of the remote class’s name. The <method–descriptor class=”xxx” method=”yyy”>, where xxx is the name of the class from which WSDL is generated and yyy is his method, identifies the method. This tag has as many descendants as method’s parameters. The descendants have the following form: <param name=”xxx” type=”yyy”>, where xxx is the name of the parameter to be used in message and port type generation and yyy is their type. If <method-descriptor> is present his descendant must correctly describe the method’s parameter number, order and type. If any of this parameters is not correct then it is used p0, p1 … as parameters names (order respectively) and no exception will be thrown.

MarshalDescription.xml

marshaler-classname : Stringmarshaled-class : String

data-marshaler

1

*

<marshal-descriptor><bean name="calculator"> <soapname>tester</soapname> <method-descriptor class="mycal.calRemote" method="add"> <param name="first" type="float"/> <param name="second" type="float"/> </method-descriptor> </bean> <data-marshaler> <marshaler-classname>ADataMarshaler</marshaler-classname> <marshaled-class>A</marshaled-class> </data-marshaler>

<data-marshaler> <marshaler-classname>BDataMarshaler</marshaler-classname> <marshaled-class>B</marshaled-class> </data-marshaler></marshal-descriptor>

marshal-desctiption


56/271

Examples

This section will provide a short guide to the examples, supplied with the distribution. The examples can be found in <SAPj2eeEngine_install_dir>/docs/examples/WebServices/soap/ directory.

Example 1 – Calculator

This is the simplest example provided - an application, which is also shipped with the SAP J2EE Engine. It is just an Enterprise Java Bean, which has several methods for doing simple calculations on float numbers. The whole process is handled by the framework automatically.

The following procedure will show the process of deploying the bean as a Web service, generating the WSDL, generating proxy and calling the proxy methods:

Deploy the calc.ear file using the DEPLOY shell command or the Deploy Tool coming with the installation.

Use the Web services framework to access the deployed bean. This issue is covered in “4. Setting up Web Service Framework” section of this document.

Browse to save the WSDL in the desired directory. For additional information about the WSDL, see the table below.

Use the ProxyGenerator Tool to generate a proxy from the WSDL file. For more information, see “7.1. SAP J2EE Engine SOAP Proxy Generator”.

Run the CalcServiceTester.java. It uses the generated proxy to call bean’s methods.

Location

Calculator/Server/calc.ear

Source Calculator/Server/source/*.*

Client Proxy

Calculator/Client/source/CalcService/CalcService.java

Client Tester

Calculator/Client/source/CalcService/CalcServiceTester.java

reference.txt line

none


57/271

WSDL http://localhost/soapdispatcher?WSDL=Calc

Example 2 – Simple

This example also is handled fully by the framework. But it uses several Java simple types, as well as simple types wrapper classes like Integer, Short, etc. Also arrays are internally supported.

Location Simple/Server/simple.ear

Source Simple/Server/source/*.*

Client Proxy

-

Client Tester

-

reference.txt line

none

WSDL http://localhost/soapdispatcher?WSDL=SimpleBean

Example 3 – Complex1

This example shows a very simple use of DataMarshalers. The enterprise bean takes one class, and the DataMarshaler handles this class. Again the framework handles the WSDL generation, but this time using the provided DataMarshaler. To deploy and run this example, you must add the line specified in the table below to the <SAPj2eeEngine_install_dir>/alone/managers/reference.txt or <SAPj2eeEngine_install_dir>/cluster/server/managers/reference.txt, so that the J2EE Engine can find the classes.

Location

Complex1/Server/complex1.ear

Source Complex1/Server/source/*.*

Client -


58/271

Proxy

Client Tester

-

reference.txt line

reference Complex1 library:inqmyxml

WSDL http://localhost/soapdispatcher?WSDL=Complex1Bean

Example 4 – Complex2

This is the most complex example provided. It uses two user classes, the one used by the other. Also two DataMarshalers are provided. Again you must add an additional line to <SAPj2eeEngine_install_dir>/alone/managers/reference.txt or <SAPj2eeEngine_install_dir>/cluster/server/managers/reference.txt file, which is specified in the providing table.

Location

Complex2/Server/complex2.ear

Source Complex2/Server/source/*.*

Client Proxy

-

Client Tester

-

reference.txt line

reference Complex2 library:inqmyxml

WSDL http://localhost/soapdispatcher?WSDL=Complex2Bean

Example 5 – EchoServlet

This example shows the usage of JAXMServlet to receive SOAPMessages in a servlet and to return responses. In addition keep in mind that the corresponding line in the


59/271

table below must be added in <SAPj2eeEngine_install_dir>/alone/managers/reference.txt or <SAPj2eeEngine_install_dir>/cluster/server/managers/reference.txt file. In order to run the example the following JAR files must be added to your classpath - inqmyxml.jar;inqmysoap.jar;activation.jar;mail.jar;jsse.jar;jnet.jar. These files are located in <SAPj2eeEngine_install_dir>/cluster/server/additional-lib/ or <SAPj2eeEngine_install_dir>/alone/additional-lib/ directory. It is not necessary to include jaxm.jar file in your classpath, because it is part of the inqmysoap.jar file.

Location EchoServlet/Server/echo.ear

Source EchoServlet/Server/EchoServlet.java

Client Tester

EchoServlet/Client/EchoServletCaller.java

reference.txt line

reference Echo library:inqmyxml

Example 6 – UDDI4J

The folder <SAPj2eeEngine_install_dir>/docs/examples/WebServices/soap/uddi4j/ contains several examples taken from the IBM UDDI Package. Before running them you must perform the steps required to set up the UDDI4J package to work with SAP J2EE Engine. For more information see “8. UDDI4J Pluggability” section.


60/271

References

W3C Working Draft "SOAP Version 1.2 Part 1: Messaging Framework", Martin Gudgin, Marc Hadley, Jean-Jacques Moreau, Henrik Frystyk Nielsen, 2 October 2001 (See http://www.w3.org/TR/2001/WD-soap12-part1-20011002/.)

W3C Working Draft "SOAP Version 1.2 Part 2: Adjuncts", Martin Gudgin, Marc Hadley, Jean-Jacques Moreau, Henrik Frystyk Nielsen, 2 October 2001 (See http://www.w3.org/TR/2001/WD-soap12-part2-20011002/.)

W3C Recommendation "XML Schema Part 1: Structures", Henry S. Thompson, David Beech, Murray Maloney, Noah Mendelsohn, 2 May 2001. (See http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/.)

W3C Recommendation "XML Schema Part 2: Datatypes", Paul V. Biron, Ashok Malhotra, 2 May 2001. (See http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/.)

W3C Recommendation "Namespaces in XML", Tim Bray, Dave Hollander, Andrew Layman, 14 January 1999. (See http://www.w3.org/TR/1999/REC-xml-names-19990114/.)

W3C Recommendation "Extensible Markup Language (XML) 1.0 (Second Edition)", Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, 6 October 2000. (See http://www.w3.org/TR/2000/REC-xml-20001006/.)

W3C Note "Simple Object Access Protocol (SOAP) 1.1", Don Box, David Ehnebuske, Gopal Kakivaya, Andrew Layman, Noah Mendelsohn, Henrik Nielsen, Satish Thatte, Dave Winer, 8 May 2000. (See http://www.w3.org/TR/SOAP/.)

Java API for XML Based RPC (JAXRPC) v0.5 - http://jcp.org/aboutJava/communityprocess/first/jsr101/

UDDI4J – IBM’s UDDI Implementation – http://www.uddi4j.org/.

Java API for XML Parsing - http://java.sun.com/xml/jaxp/index.html/.

Web Services Definition Language 1.1 (Note) - http://www.w3.org/TR/wsdl.

Java API for XML Messaging 0.94 - http://java.sun.com/xml/jaxm/index.html.

Java API for XML Registries 0.7 (JAXR). Public Review Draft 2: 11/13/2001 - http://java.sun.com/xml/jaxr/index.html.


61/271

Chapter 3 SAP XML Toolkit for Java

• Basic Concepts

• Java API for XML Parsing (JAXP)

• Advanced Techniques

• SAP XML Toolkit for Java FAQ

• References


62/271

Basic Concepts

XSL Overview

XSL (Extensible Style Language) consists of two separate halves – a transformation language and a formatting language. Each of these can function independently from each other. The transformation language basic function is to transform an XML document using a XSL Stylesheet Processor into another XML document. The transformed XML document can use DTD and markup from the original or only a specified set of tags.

XSL Stylesheet Processing

Tree Transformation

An XML Stylesheet Processor executes the whole process of transforming. It accepts an XML document and an XSL stylesheet and transforms the source XML document into another. Thus the tree transformation phase of the process is accomplished, constructing the result tree.

Formatting Phase

The second phase is performed through a formatter. For instance it can be a rendering engine inside a browser. The whole process is executed by including formatting semantics in the result tree. These semantics represent classes of formatting objects. Each node of the result tree is a formatting object. Additional formatting properties facilitate representation of the result tree.

JAXP Overview

JAXP is a standard Sun API that allows different XML-processing Java software to be easily plugged in and interchanged. The whole process consists of simply changing a system property in a system that supports only one JAXP implementation, without dealing with all the pre-existing code. If the system supports more than one implementation, it is recommended to use classloaders – you have to reference from your application the library that includes the JAR file, which contains the JAXP implementation. Problems may occur if the new parser does not support some of the features that the old one supplied.

JAXP includes interfaces and abstract classes that ensure access to DOM and SAX parsers, as well as to XSLT transformers.

In order to obtain a SAXParser, the user must first get its corresponding SAXParserFactory through the static SAXParserFactory.newInstance() method and then the SAXParser itself by the factory newSAXParser() method.

Similarly, DocumentBuilder-s (DOM parsers) and their factories are obtained through DocumentBuilderFactory, and Transformer-s (XSLT transformers) are obtained


63/271

through TransformerFactory. Every factory's newInstance() method goes through an algorithm to determine the JAXP implementation. The algorithm is the following:

• Search for a system property named: o javax.xml.parsers.DocumentBuilderFactory o javax.xml.parsers.SAXParserFactory o javax.xml.transform.TransformerFactory

If no property is found, then the jaxp.properties file of the installed JDK is searched for properties having such names. If this file is not found, or it does not contain a property for the searched factory, then the actual searching logic is performed, used also in the J2EE Engine. It gets the classloader of the appropriate factory interface, uses this classloader to load a resource using Classloader.getResourceAsStream("") from the META-INF/services/ directory (for example, META-INF/services/javax.xml.parsers.DocumentBuilderFactory)

If this resource is found, the contents of this file is a string specifying the class for the JAXP Factory Implementation. Then using the same Classloader, this factory is loaded. In case no such file is found, the fallback value of the JAXP implementation is returned.

For instance, a SAXParser can be obtained through:

SAXParserFactory f = SAXParserFactory.newInstance(); SAXParser p = f.newSAXParser();

And used through:

org.xml.sax.helpers.DefaultHandler h = new MyHandler(); p.parse(filename, h);

The JAXP view of SAP J2EE Engine XML tools is placed in the com.inqmy.lib.jaxp package. It supports the two basic API-s, DOM, SAX, and XSLT transformations.

It is recommended always to use classloader references.

XML Schema Validator

The XML Schema is a language defining the structure of an XML file. It is expected that soon it will completely replace the previous DTD language, because of its much greater expressive capabilities.

In order to use our implementation of XML Schema Validation, you have to do one of the following:

• Use the command line tool - sch.bat

• Use: DocumentBuilderFactory.setAttribute(“http://www.inqmy.com/schema”, “myschema.xsd”);

• For example: import com.inqmy.lib.schema.validator.SchemaValidator; boolean result = new SchemaValidator().validate(nodeXML, nodeXSD);


64/271

where nodeXML and nodeXSD are the DOM trees of the XML instance and the schema respectively.

Schema to Java Generator

Though the purpose of the XML Schema is to validate XML instances. It is often used for defining abstract structures in a language-independent way. The development of a SOAP proxy generator for WSDL service descriptions enforced the appearance of such a utility.

The generator uses the Java naming convention when generating classes representing schema types. The transformation of a schema complex type name to a Java method or class identifier conforms to the part of the JAXRPC specification, which describes such name transformations.

One can use it in the following ways:

• Use the command line tool, gen.bat: Usage: sch filename.xsd output_directory_name output.package.name

• Use the following code:

Schema schema = new Schema(); schema.loadRaw(inputStream); schema.generateAll(new File("output_directory_name"),"output.package.name");


65/271

Java API for XML Parsing (JAXP)

The following section aims to represent to the reader several Java-oriented examples, which introduce the basic features of the parsing process.

Introduction to DOM

DOM is a standard, designed to provide the developer with an easy-to-manipulate tree structure, which represents an XML document. This structure is appropriate for applications that need to access and manipulate the XML document directly. Since the whole tree is maintained in the memory, the DOM-based application can deteriorate the J2EE Engine performance.

If you do not need to manipulate the XML document, it is recommended to use SAX – it is faster and takes less memory.

DOM can be used either to traverse an existing DOM Tree, and extract specific information, or to build a DOM Document in memory, and then either forward it to some application, which will process it, or to serialize it, thus creating an XML file.

Now the most important methods and interfaces will be lined out. Although many not so important methods will be skipped, the whole definition and description of these methods can be found either in the javadoc documentation of the SAP XML Toolkit for Java, or on the www.w3c.org site – section DOM.

Building DOM Trees through Parsing

The easiest way to get a DOM Tree is to parse an XML file using a DocumentBuilder. Then you can traverse the Document object and extract what you need. The JAXP Framework provides several classes to do this.

In general all you need to do is to invoke DocumentBuilderFactory.newInstance() in order to get an instance of the DocumentBuilderFactory. Then you can use this instance to get a new DocumentBuilder – (newDocumentBuilder()). And finally use the DocumentBuilder instance to parse an XML file, using DocumentBuilder.parse(InputSource). You can further specify whether you want your DocumentBuilder to be validating - DocumentBuilderFactory.setValidating(boolean), or to be namespace-aware - DocumentBuilderFactory.setNamespaceAware(boolean).

javax.xml.parsers.DocumentBuilderFactory

o public static DocumentBuilderFactory newInstance() - obtains a new instance of a DocumentBuilderFactory. This static method creates a new factory instance. The procedure to determine the DocumentBuilderFactory implementation class to be loaded is described above.

Once an application has obtained a reference to a DocumentBuilderFactory, it can use the factory to configure and obtain parser instances.


66/271

• public DocumentBuilder newDocumentBuilder() - creates a new instance of a DocumentBuilder using the currently configured parameters.

• public void setNamespaceAware(boolean awareness) - specifies that the parser produced by this code will provide support for XML namespaces. By default the value of this is set to false.

• public void setValidating(boolean validating) - specifies that the parser produced by this code will validate documents as they are parsed. By default the value of this is set to false.

javax.xml.DocumentBuilder

• public Document parse(InputSource is) • public Document parse(InputStream is) • public Document parse(Reader reader) • public Document parse(File file) • public Document parse(String uri)

Parse the content of the given input source as an XML document and return a new DOM Document object.

• public Document newDocument() - obtains a new instance of a DOM Document object to build a DOM tree.

Traversing

org.w3c.dom.Node

This is the base class of all DOM Objects – Document, Element, Attr, Text, etc. It has several methods, which can be used to traverse a document.

• public org.w3c.dom.Node getFirstChild() - the first child of this node. If there is no such node, returns null.

• public org.w3c.dom.Node getPreviousSibling() - the node immediately preceding this node. If there is no such node, returns null.

• public org.w3c.dom.Node getNextSibling() - the node immediately following this node. If there is no such node, returns null.

• public org.w3c.dom.NamedNodeMap getAttributes() - a NamedNodeMap containing the attributes of this node (if it is an Element) or null otherwise.

• public org.w3c.dom.Document getOwnerDocument() - the Document object associated with this node. This is also the Document object used to create new nodes. When this node is a Document or a DocumentType, which is not used with any Document yet, this is null.

• public org.w3c.dom.Node removeChild (org.w3c.dom.Node oldChild) - removes the child node indicated by oldChild from the list of children, and returns it.

• public org.w3c.dom.Node appendChild (org.w3c.dom.Node newChild) - adds the node newChild to the end of the list of the children of this node. If the newChild is already in the tree, it is first removed.

• public String getNodeName() - the name of this node, depending on its type; see the table above.

• public String getNodeValue() - the value of this node, depending on its type; see the table above. When it is defined to be null, setting it has no effect.


67/271

• public short getNodeType() - a code representing the type of the underlying object, as defined above. The most used kinds of node-types are: o Node.ELEMENT_NODE – for element nodes o Node.DOCUMENT_NODE – for document nodes o Node.TEXT_NODE – for text nodes o Node.COMMENT_NODE – for comment nodes

• public org.w3c.dom.Node getParentNode() - the parent of this node. All nodes, except Attr, Document, DocumentFragment, Entity, and Notation may have a parent. However, if a node has just been created and not yet added to the tree, or if it has been removed from the tree, this is null.

• public org.w3c.dom.NodeList getChildNodes() – returns a NodeList that contains all children of this node. If there are no children, this is a NodeList without nodes.

org.w3c.dom.Element

This class is used to represent an Element node. It may have children attributes. There are also methods to search for nodes with a specific name among the descendants of this node. For an Element node, invoking Node.getNodeType() returns Node.ELEMENT_NODE. Several methods from the Element interface are described below:

• public String getAttribute (String name) - retrieves an attribute value by name.

• public void setAttribute (String name, String value) - adds a new attribute. If an attribute with that name is already present in the element, its value is changed to be the same as the value parameter. This value is a simple String. It is not parsed as it is being set. So any markup (such as syntax to be recognized as an entity reference) is treated as literal text and needs to be appropriately escaped by the implementation when it is written out. In order to assign an attribute value that contains entity references, the user must create an Attr node, and then any Text and EntityReference nodes, build the appropriate subtree, and use setAttributeNode to assign it as the value of an attribute. To set an attribute with a qualified name and namespace URI, use the setAttributeNS method.

• public NodeList getElementsByTagName (String name) - returns a NodeList of all descendent Elements with a given tag name, in the order in which they are encountered in a preorder traversal of this Element tree.

org.w3c.dom.Text

This node type represents all the text content inside a Document.

• public String getData() - the character data of the node that implements this interface.

• public void setData (String data) – sets the character data for this node.

org.w3c.dom.Comment

This node type is used to represent a comment in the XML.


68/271

org.w3c.dom.Document

This is the root node of an XML Document. After the XML is passed, this is the type of node you get from the parser. It represents the whole XML document, that is – the root element, the processing instructions and comments on the root level, parts of the DTD (Entity declarations and Notations). For traversing the following relevant methods are used:

• public Element getDocumentElement() - this is a convenient attribute that allows direct access to the child node, that is the root element of the document.

• public NodeList getElementsByTagName (String tagname) - returns a NodeList of all the Elements with a given tag name in the order in which they are encountered in a preorder traversal of the Document tree.

org.w3c.dom.NodeList

This interface is used to represent a list of nodes. There are two methods, which are useful:

• public Node item(int index) - returns the index-th item in the collection. If index is greater than or equal to the number of nodes in the list, returns null.

• public int getLength() - the number of nodes in the list. The range of valid child node indices is 0 to length-1 inclusively.

org.w3c.dom.NamedNodeMap

This interface is used to represent a collection of nodes, which are to be accessed by their names.

• public Node getNamedItem(String name) - retrieves a node specified by the name.

• public Node item(int index) - returns the index-th item in the map. If index is greater than or equal to the number of nodes in this map, returns null.

• public int getLength() - the number of nodes in this map. The range of valid child node indices is from 0 to length-1 inclusively.

Building DOM Trees from a Document

To build a DOM Tree, you have to take an empty Document instance. In JAXP this task is performed by getting an instance of DocumentBuilderFactory. Then from this instance you get a new instance of a DocumentBuilder. And then from the instance of the DocumentBuilder you invoke newDocument().

javax.xml.DocumentBuilder

• public abstract Document newDocument() – obtains new instance of a DOM Document object to build a DOM tree.


69/271

org.w3c.dom.Document

• public Element createElement(String tagName) - creates an element of the type specified. The instance returned implements the Element interface, so attributes can be specified directly on the returned object. In addition, if there are known attributes with default values, Attr nodes representing them are automatically created and attached to the element.

• public Text createTextNode(String data) - creates a Text node using the specified string.

• public Comment createComment(String data) - creates a Comment node using the specified string.

• public ProcessingInstruction createProcessingInstruction (String target, String data) - creates a ProcessingInstruction node using the specified name and data strings.

• public Node importNode(Node importedNode, boolean deep) - imports a node from another document to this document. The returned node has no parent (parentNode is null). The source node is not altered or removed from the original document. This method creates a new copy of the source node.

org.w3c.dom.Node

• public Node insertBefore(Node newChild, Node refChild) - inserts the node newChild before the existing child node refChild. If refChild is null, insert newChild at the end of the list of children. If newChild is a DocumentFragment object, all of its children are inserted, in the same order, before refChild. If the newChild is already in the tree, it is first removed.

• public Node replaceChild(Node newChild, Node oldChild) - replaces the child node oldChild with newChild in the list of children, and returns the oldChild node. If newChild is a DocumentFragment object, oldChild is replaced by all of the DocumentFragment children, which are inserted in the same order. If the newChild is already in the tree, it is removed.

• public Node removeChild(Node oldChild) - removes the child node indicated by oldChild from the list of children, and returns it.

• public Node appendChild(Node newChild) - adds the node newChild to the end of the list of children of this node. If the newChild is already in the tree, it is first removed.

DOM Examples

Building DOM through Parsing

Example 1:

public class JAXPDOMExample { public static void main(String args[]) { try { String xml= "data/rich_ii.xml"; //get a DocumentBuilderFactory from the underlying //implementation DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance(); factory.setValidating(true); //get a DocumentBuilder from the factory DocumentBuilder builder = factory.newDocumentBuilder(); //parse the document Document document = builder.parse(xml);


70/271

DOMTraverser domTester = new DOMTraverser(); domTester.traverse1(document); } catch (Exception e) { //if there was some error while parsing the file e.printStackTrace(); } }

Traversing

Example 1:

public void traverse1(Node node) { do { System.out.println("Node: name=" + node.getNodeName() + ", value=" + node.getNodeValue() + ", type=" + node.getNodeType()); if (node.getFirstChild() != null) { System.out.println("Processing children:"); traverse1(node.getFirstChild()); } } while ((node = node.getNextSibling()) != null); }

Example 2:

public void traverse2(Node node) { //Get the children of this Node NodeList children = node.getChildNodes(); //go through all the children of the node for (int i=0; i<children.getLength(); i++) { //get the next child Node child = children.item(i); //get the type of the child short childType = child.getNodeType(); if (childType == Node.ELEMENT_NODE) { //if the child is an Element then print the start and end //tags and recurse the content String nodeName = child.getNodeName(); System.out.print("<" + nodeName + ">"); traverse2(child); System.out.print("</" + nodeName + ">"); } else if (childType == Node.TEXT_NODE) { //if the child is a Text node just print the text content String data = child.getNodeValue(); System.out.print(data); } } }

Example 3:

public void traverse3(Node node, int indent) { for (int i = 0; i < indent; i++) { System.out.print(" "); } int type = node.getNodeType(); switch (type) { case Node.ATTRIBUTE_NODE:


71/271

System.out.println("ATTRIBUTE_NODE"); break; case Node.CDATA_SECTION_NODE: System.out.println("CDATA_SECTION_NODE"); break; case Node.COMMENT_NODE: System.out.println("COMMENT_NODE"); break; case Node.DOCUMENT_FRAGMENT_NODE: System.out.println("DOCUMENT_FRAGMENT_NODE"); break; case Node.DOCUMENT_NODE: System.out.println("DOCUMENT_NODE"); break; case Node.DOCUMENT_TYPE_NODE: System.out.println("DOCUMENT_TYPE_NODE"); break; case Node.ELEMENT_NODE: System.out.println("ELEMENT_NODE"); NamedNodeMap atts = node.getAttributes(); for (int i = 0; i < atts.getLength(); i++) { Node att = atts.item(i); traverse3(att, indent + 1); } break; case Node.ENTITY_NODE: System.out.println("ENTITY_NODE"); break; case Node.ENTITY_REFERENCE_NODE: System.out.println("ENTITY_REFERENCE_NODE"); break; case Node.NOTATION_NODE: System.out.println("NOTATION_NODE"); break; case Node.PROCESSING_INSTRUCTION_NODE: System.out.println("PROCESSING_INSTRUCTION_NODE"); break; case Node.TEXT_NODE: System.out.println("TEXT"); break; default: System.out.println("???"); break; } for (Node c = node.getFirstChild(); c != null; c = c.getNextSibling()) { traverse3(c, indent + 1); } }

Introduction to SAX

SAX uses callback approach to parse an XML document. Thus greater efficiency is achieved when parsing large XML documents. Now we will introduce the most important methods and interfaces, used when processing an XML using SAX. For more information and full description please check the javadoc, or the references at the end of this document.

First a basic description of the interfaces used in the call-back will be provided, and then the ways of setting them to a SAXParser, and parsing XML Files.


72/271

org.xml.sax.ContentHandler

This is the main interface that most SAX applications implement. If the application needs to be informed of basic parsing events, it implements this interface and registers an instance with the SAX parser using the setContentHandler method. The parser uses the instance to report basic document-related events as the start and end of elements and character data.

• public void startDocument() - receives notification of the beginning of a document.

• public void endDocument() - receives notification of the end of a document.

• public void startElement(String namespaceURI, String localName, String qName, Attributes atts) - receives notification of the beginning of an element. The namespaceURI, localName and qName parameters are only relevant when namespaceAware processing is used. For the simple case where a simple XML file is parsed then namespaceURI is null, and qName is equal to localName – the name of the XML tag.

• public void endElement(String namespaceURI, String localName, String qName) - receives notification at the end of an element.

• public void characters(char[] ch, int start, int length) - receives notification of character data.

• public void processingInstruction(String target, String data) - receives notification of a processing instruction.

org.xml.sax.Attributes

This interface is used to represent a list of attributes. Each attribute can be accessed in three different ways: by index, by name or by NamespaceQualified name.

• public int getLength() - returns the number of attributes in the list. • public String getQName(int index) - looks up an attribute's XML 1.0

qualified name by index. • public String getType(int index) - looks up an attribute's type by

index. The attribute type is one of the strings "CDATA", "ID", "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES", or "NOTATION" (always in capital letters).

• public String getValue(int index) - looks up an attribute's value by index.

• public int getIndex(String qName) - looks up the index of an attribute by XML 1.0 qualified name.

• public String getValue(String qName) - looks up an attribute’s value by XML 1.0 qualified name.

• public String getType(String qName) - looks up an attribute's type by XML 1.0 qualified name.

Using SAX Parser

In order to process an XML document using SAX, you have to take SAXParser from a SAXParserFactory and supply it with a source document and an instance of a class, which extends org.xml.sax.helpers.DefaultHandler. This class – DefaultHandler is a class, which has default, empty, implementations of all the methods of the ContentHandler interface (and also - ErrorHandler, DTDHandler), and itself implements all these interfaces. So if you need to be notified when an


73/271

element is starting, you just need to extend this class and override the startElement() method.

javax.xml.parsers.SAXParserFactory

• public static SAXParserFactory newInstance() – similar to the DocumentBuilderFactory.newInstance().

• public SAXParser newSAXParser() – returns a SAXParser instance, which can be used to parse files.

• public void setNamespaceAware(boolean awareness) - specifies that the parser produced by this code will provide support for XML namespaces. By default the value is set to false.

• public void setValidating(boolean validating) - specifies that the parser produced by this code will validate documents as they are parsed. By default the value is set to false.

javax.xml.parsers.SAXParser

• public void parse(InputSource is, DefaultHandler h) – you can also use InputStream, Reader, File, String, as the source for the parse.

Examples

SAX Parsing

Example 1:

public class JAXPSAXExample { public static void main(String args[]) { try { String xml = "data/cars.xml"; //get a SAXParserFactory from the underlying implementation SAXParserFactory factory = SAXParserFactory.newInstance(); //get a new SAXParser from the factory SAXParser parser = factory.newSAXParser(); //parse the specified file using the SAXTreeStructure //handler parser.parse(xml, new SAXTreeStructure()); } catch (Exception e) { // handle exception e.printStackTrace(); } }

ContentHandler, DefaultHandler Implementation

Example 1:

public class SAXTreeStructure extends DefaultHandler { public void startElement(String namespaceURI, String localName, String rawName, Attributes atts) { System.out.println("Start Element: " + rawName); } public void endElement(String namespaceURI, String localName, String rawName) { System.out.println("End Element : " + rawName); }


74/271

public void characters(char []data, int off, int length) { System.out.println("Characters : " + new String(data, off, length)); } }

Example 2:

public class JAXPSAXExample2 extends DefaultHandler { public void setDocumentLocator(Locator locator) { System.out.println("Method setDocumentLocator(" + locator + ")"); } public void startDocument() throws SAXException { System.out.println("Method startDocument()."); } public void endDocument() throws SAXException { System.out.println("Method endDocument()."); } public void startPrefixMapping(String prefix, String uri) throws SAXException { System.out.println("Method startPrefixMapping(" + prefix + ", " + uri + ")."); } public void endPrefixMapping(String prefix) throws SAXException{ System.out.println("Method endPrefixMapping(" + prefix + ")."); } public void startElement(String namespaceURI, String localName, String qName, Attributes atts) throws SAXException { System.out.println("Method startElement(" + namespaceURI + ", " + localName + ", " + qName + ", " + atts + ")."); } public void endElement(String namespaceURI, String localName, String qName) throws SAXException { System.out.println("Method endElement(" + namespaceURI + ", " + localName + ", " + qName + ")."); } public void characters(char[] ch, int start, int length) throws SAXException { System.out.println("Method characters(" + new String(ch, start, start + length) + ")."); } public void ignorableWhitespace(char[] ch, int start, int length) throws SAXException { System.out.println("Method ignorableWhitespace(" + new String(ch, start, start + length) + ")."); } public void processingInstruction(String target, String data) throws SAXException { System.out.println("Method processingInstruction(" + target + ", " + data + ")."); } public void skippedEntity(String name) throws SAXException { System.out.println("Method skippedEntity(" + name + ")."); } public InputSource resolveEntity(String publicId, String systemId) throws SAXException { System.out.println("Method resolveEntity(" + publicId + ", " + systemId + "). Resolving to: data\\" + systemId); return new InputSource("data/" + systemId); } public static void main(String[] args) throws Exception {


75/271

String xml = "data/rich_ii.xml"; SAXParserFactory factory = SAXParserFactory.newInstance(); factory.setValidating(true); SAXParser parser = factory.newSAXParser(); System.out.println(" validating: " + parser.isValidating()); System.out.println(" namespace-aware: " + parser.isNamespaceAware()); System.out.println(""); parser.parse(xml, new JAXPSAXExample2()); } }

XSL Transformations

You can use the XSL Transformation part of JAXP, to transform source documents into result documents, by applying a stylesheet or just convert from one type of source (for example DOM), to some different kind of result (for example SAX). The source and result will represent one and the same document. You could also apply indenting to a document, by giving it as a source document, setting the transformer an OutputProperty to use indenting, and then set the result to be some other file.

Source Types

javax.xml.transform.Source

This is the base class for all kinds of sources.

javax.xml.transform.stream.StreamSource

This class represents a source, which is being read from a stream. This stream could be an InputStream, Reader, File, URL. You just have to use the correct constructor: StreamSource(InputStream), StreamSource(Reader), StreamSource(File) or StreamSource(String url). Keep in mind that when reading from a stream, it is not a duty of the transformer to close this stream. Only when reading from a File or url, the parser opens a stream to this resource and takes care to close it at the end. If you use a reader or an input stream, it is recommended also to set a systemID with the appropriate setSystemId method. By convention, the systemID is the URL to the stream or the reader. The systemID is used also for retrieve relative URIs inside the appropriate source file.

javax.xml.transform.dom.DOMSource

This class represents a source, which is either a DOM Document (org.w3c.dom.Document), or any other kind of node. The parser uses this tree as the source document. The general constructor is DOMSource(Node node);

javax.xml.transform.sax.SAXSource

This class represents a source, which is a SAX DefaultHandler. That is, the parser reads the call-backs (called on a DefaultHandler implementation, by some other parser) and constructs its source data. You might use the constructor – SAXSource(DefaultHandler handler);


76/271

Result Types

javax.xml.transform.Result

This is the base class for all kinds of results

javax.xml.transform.stream.StreamResult

Similarly to StreamSource, this class is used when you want the result to be written in a stream (OutputStream, Writer, File). The constructors are: StreamResult(OutputStream), StreamResult(Writer), StreamResult(File), StreamResult(String url). Keep in mind that it is not a responsibility of the transformer to close a StreamResult constructed with OutputStream or Writer. As for the StreamSource, it is recommended to set the systemID if you use a constructor with an OutputStream or a Writer.

javax.xml.transformer.dom.DOMResult

Using this kind of result you might specify that you want the result to be a DOM Tree, which will be built by the transformer. The constructor is DOMResult(Node root).

javax.xml.transformer.sax.SAXResult

Using this result you might supply an instance of a class extending DefaultHandler, which methods will be called in order to let the user create the result himself. The constructor is SAXResult(DefaultHandler handler).

Output Properties

These properties can be set on the transformer to change some properties like indent, xml-declaration, type (XML, HTML, text), etc. of the result. They are the same that can be applied to a transformation when using the xsl:output – node in the stylesheet. Here only the most important ones will be lined out. For further information check the javadoc documentation of the XML Toolkit, or Section 16 of the XSLT Documentation.

Usage

These are predefined strings in the class javax.xml.transform.OutputKeys, which you might set to the transformer using: transformer.setOutputProperty(String name, String value), on an instance of the transformer.

• OutputKeys.VERSION – to control the version of the result document • OutputKeys.METHOD – can be xml, html, text, or some namespace qualified

name. • OutputKeys.ENCODING – sets the encoding of the result. It is very useful

when you want to transform one source document in UTF-8 to ISO-8859-1, or some other encoding.

• OutputKeys.DOCTYPE_PUBLIC and OutputKeys.DOCTYPE_SYSTEM – adds a <!DOCTYPE (root-tag) SYSTEM (System_key) (Public_key)> to the result.

• OutputKeys.INDENT – “yes” or “no”. Allows you to control, weather the result should be indented or not. In this way you might add indenting to some XML


77/271

file, just by transforming it from a StreamSource to a StreamResult, and setting this OutputProperty to “yes”.

Transforming Without Stylesheet – Converting

To transform from one kind of source to some other kind of result you must get an instance of TransformerFactory and then use newTransformer() to get a transformer, which is not associated with a stylesheet:

TransformerFactory factory = TransformerFactory.newInstance(); Transformer transformer = factory.newTransformer();

Now you might, optionally, set some OutputProperties to the transformer:

transformer.setOutputProperty(OutputKeys.INDENT, “yes”);

And finally do a transformation:

1. Stream -> Stream (Changing the indent)

transformer.transform(new StreamSource(“source.xml”), new StreamResult(“Result.xml”);

2. Stream -> DOM (also known as DOM Parsing)

transformer.transform( new StreamSoruce(“source.xml”), new DOMResult(dom_node));

3. DOM -> SAX

transformer.transform( new DOMSource(dom_node), new SAXResult(sax_defaulthandler));

4. Check the examples in the SAP J2EE XML Toolkit for more.

Transforming Without Stylesheet

This procedure is almost the same as was described in 2.3.4. The difference is that when getting the transformer instance with newTransformer, another overload is used. That is newTransformer(Source source):

Transformer transformer = factory.newTransformer( new StreamSource ( new FileReader(“mystylesheet.xsl”));

Examples

Converting Example

public class JAXPSourceConvertExample { public static void main(String[] args) throws Exception { String xml = "data/current.xml"; // Obtaining an instance of the factory TransformerFactory factory = TransformerFactory.newInstance(); Transformer transformer = factory.newTransformer(); DOMResult domResult = new DOMResult(); // stream -> dom


78/271

System.out.println("\nStream -> DOM "); transformer.transform(new StreamSource(xml), domResult); // sax -> stream System.out.println("\nSAX -> Stream "); transformer.transform(new SAXSource(new InputSource(xml)), new StreamResult(System.out)); // dom -> stream System.out.println("\nDOM -> Stream"); transformer.transform(new DOMSource(domResult.getNode()), new StreamResult(System.out)); // stream -> sax System.out.println("\nStream -> SAX"); transformer.transform(new StreamSource(xml), new SAXResult((ContentHandler)new SAXTreeStructure())); // sax -> dom domResult = new DOMResult(); System.out.println("\nSAX -> DOM"); transformer.transform(new SAXSource(new InputSource(xml)), domResult); // dom -> sax System.out.println("\nDOM -> SAX"); transformer.transform(new DOMSource(domResult.getNode()), new SAXResult((ContentHandler)new SAXTreeStructure())); } }

XSL Transformation

public class JAXPXSLTExample { public static void main(String args[]) { //get a new TransformerFactory from the underlying //implementation TransformerFactory factory = TransformerFactory.newInstance(); Transformer transformer = null; Templates template = null; StreamSource xmlSource = null; StreamSource xslSource = null; StreamResult result = null; try { // a new StreamSource from a file name xmlSource = new StreamSource("data/cars.xml"); xslSource = new StreamSource("data/cars1.xsl"); // a new StreamResult to a file name (it is automatically //closed on exit) result = new StreamResult("data/cars1.html"); // get a new Templates object for this stylesheet template = factory.newTemplates(xslSource); // get a new Transformer from the Templates transformer = template.newTransformer(); // perform the transformation transformer.transform(xmlSource, result); // it is not needed to close the Stream result since it is //output to a file name } } }


79/271

Advanced Techniques

Integration of XSL with Other Languages

Java Integration (Java Language Binding)

Allows method invocation upon existing Java classes and objects (i.e. invocation of static and instance methods) and object creation (constructor invocation) upon existing classes.

To implement an extension function in Java, stylesheet developers associate an implementation to their extension function namespace prefix using an xsl:script element with language=”java” as in the following example:

<?xml version="1.0"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0" xmlns:date="uri.any"> <xsl:script implements-prefix="date" language="java" src="java:com.example.datestuff.DateRoutines"/> <xsl:template match="/"> <OrderDate> <xsl:value-of select="date:format(/order/date,'MM/DD/YY')"/> </OrderDate> </xsl:template> </xsl:stylesheet>

For Java, the value of the src attribute on xsl:script is a URI reference identifying a Java class. The methods of this class implement the functions, which expanded names, have the namespace URI specified by the implements-prefix attribute. The URI specified by the src attribute may use the java: URI scheme: src="java:fully.qualified.ClassName"; the XSLT processor may also allow the URI to use other URI schemes to locate a resource containing the Java class file.

Here is an example XSL document that uses Java Language Binding:

<?xml version="1.0"?> <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:myobj="com.inqmy.lib.xml.parser.Myobj"> <xsl:param name="myobj"/> <xsl:template match = "/"> At this moment:<xsl:value-of select="string(myobj:getToday())"/> we offer: <xsl:apply-templates/> <xsl:value-of select="myobj:callNodeList($myobj, /)"/> </xsl:template> </xsl:stylesheet>


80/271

Applying the latter to the following XML document:

<?xml version="1.0"?> <grocery name = "The red tomato"> <fruit> <article> Apples</article> <article> Pears </article> <article> Bananas </article> </fruit> <vegetables> <article>Cucumbers </article> <article> Tomatoes </article> <article> Peppers </article> </vegetables> </grocery>

Results in:

<?xml version='1.0' encoding='utf-8'?> At this moment:Wed Oct 17 17:48:53 EEST 2001 we offer: Apples Pears Bananas Cucumbers Tomatoes Peppers

In order to run this example, a parameter should be added to the transformer, prior to transformation in the following way:

Myobj my = new Myobj(); transformer.setParameter("myobj", my);

Where the class definition of the class Myobj looks like:

import org.w3c.dom.*; public class Myobj { public void callNodeList(Node n) { System.out.println(n); } public static java.util.Date getToday() { java.util.Calendar cal = ava.util.Calendar.getInstance(); return cal.getTime(); } }


81/271

Integration with Scripting Languages

Allows execution of scripts in virtually any scripting language that offers a scripting engine, compatible with the Bean Scripting Framework (BSF). Also allows function calls for the functions in the script. Short example is described briefly below:

<?xml version="1.0"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0" xmlns:my-ext="ext1" extension-element-prefixes="my-ext"> <xsl:script language="javascript" implements-prefix="my-ext"> var multiplier=2; function timelapse() {return 4;} function getdate(numdays) { var d = new Date(); var totalDays = parseInt(numdays) * multiplier; d.setDate(d.getDate() + totalDays); return d.toLocaleString(); } </xsl:script> <xsl:template match="deadline"> <p><my-ext:timelapse multiplier="4"/>We have logged your enquiry and will respond by <xsl:value-of select="string(my-ext:getdate(string(@numdays)))"/>.</p> </xsl:template> </xsl:stylesheet>

The script has to be situated in a top-level <xsl:script> element, with its language specified as an attribute.

Multiple Output Documents

The xsl:document element is used to create multiple result documents. As well as the main result document, subsidiary result documents may be available. Each subsidiary result document is created using an xsl:document element. The content of the xsl:document element is a template; this is instantiated to create a sequence of nodes; a root node is created with this sequence of nodes as its children; the tree with this root node represents the subsidiary result document. The href attribute specifies where the subsidiary document should be stored; it must be an absolute or relative URI; it must not have a fragment identifier.

For instance the following XML file:

<?xml version="1.0"?> <grocery name = "The red tomato"> <fruit> <article>Apples </article> <article>Pears </article> <article>Bananas</article> </fruit>


82/271

<vegetables> <article>Cucumbers</article> <article>Tomatoes</article> <article>Peppers</article> </vegetables> </grocery>

will be processed with the following stylesheet:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <xsl:template match="/"> <main_output> Vegetables and Fruit <xsl:apply-templates/> </main_output> </xsl:template> <xsl:template match="grocery"> <In_stock> <xsl:apply-templates/> <fruit> <xsl:value-of select = 'document("fruit\fruit.out")/fruit'> </xsl:value-of> </fruit> <vegetables> <xsl:value-of select = 'document("vegetables\vegetables.out")/vegetables'> </xsl:value-of> </vegetables> </In_stock> </xsl:template> <xsl:template match = "/grocery/fruit"> <xsl:document href = "fruit\fruit.out"> <fruit> <xsl:apply-templates/> </fruit> </xsl:document> </xsl:template> <xsl:template match = "/grocery/vegetables"> <xsl:document href = "vegetables\vegetables.out"> <vegetables> <xsl:apply-templates/> </vegetables> </xsl:document> </xsl:template> </xsl:stylesheet>

Then two files will be created - \fruit\fruit.out and \vegetables\vegetables.out, containing the fruit and vegetables in stock, respectively. The combined information will be stored in the main output.


83/271

Active XML Scanning

The JAXRPC Community draft version 0.5 specifies an interface called XMLReader. There is an interface called ActiveXMLParser, which provides a similar functionality and is located in the com.inqmy.lib.xml.parser package of the SAP XML Toolkit for Java. Although not all of the methods correspond exactly to those, specified in the draft, the purpose of this interface is the same – it specifies the behavior of the class, responsible for carrying out the step-by-step parsing process. The interface specifies six specific states in which the parser can be: initial state, start of element, end of element, character data, processing instruction and end of file. These are mapped to the numbers from 0 to 5 respectively. The methods of the interface allow the user some sort of manual control over the process – the user has the freedom (and responsibility) to notify the parser to proceed to the next stage of the parsing process. Left “on his own”, the parser never does a forward step.

As an example of the features, described above, one could consult the XMLReaderExapmle.java file, available in the <SAPj2eeEngine_install_dir>/docs/examples/xml_toolkit directory coming with the SAP XML Toolkit for Java (it uses a specific implementation of the described interface, that is located in the com.inqmy.lib.xml.parser.ActiveXMLParser package.)

Evaluating XPath Queries on DOM Objects

The XPath 1.0 recommendation (available at http://www.w3.org/TR/xpath) stated: “XPath is the result of an effort to provide a common syntax and semantics for functionality shared between XSL Transformations [XSLT] and XPointer [XPointer].” This confines XPath to a very specific area of use. It has become obvious, though, that XPath could be useful for a wider area of purposes, including DOM. This problem has been addressed to by W3C in the DOM level3 XPath Specification (available at http://www.w3.org/TR/2001/WD-DOM-Level-3-XPath-20011031/.) The functionality described in this document is implemented in the SAP XML Toolkit for Java – it provides you with the opportunity to create XPath queries and evaluate them with respect to different context.

As an example of the features, described above, one could consult the DomXpathExapmle.java file, available in the <SAPj2eeEngine_install_dir>/docs/examples/xml_toolkit directory coming with the SAP XML Toolkit for Java (it uses a specific implementation of the described interface, that is located in the com.inqmy.lib.xml.dom.xpath package.)

Changing the Default Parser

In order to change the default parser and set a different one, replace the following code fragment in the <SAPj2eeEngine_install_dir>/alone/managers/library.txt or <SAPj2eeEngine_install_dir>/cluster/server/managers/library.txt:

library inqmyxml inqmyxml.jar with library inqmyxml newparser_jar_files, where the newparser_jar_files represents a JAR files list of the new parser. Also the following line must be added to the library.txt file:

reference core server-xml


84/271

Note: This section implies for the default parser as a part of the SAP J2EE Engine. Keep in mind that the new parser must be obligatory JAXP compliant in order to function properly.


85/271

SAP XML Toolkit for Java FAQ

Frequently Asked Questions (FAQ)

Questions

1. How can I build a DOM tree from an XML document?

How can I use a SAX -> XML Serializer?

How to match an XPath expression to an XML document, for getting a boolean result?

Using the Toolkit you receive a strange exception:

java.lang.NoSuchMethodError at com.inqmy.lib.xml.util.DOMToDocHandler.process(DOMToDocHandler.jav:50) at com.inqmy.lib.xml.util.DOMToDocHandler.process(DOMToDocHandler.java:113) at com.inqmy.lib.xml.util.DOMToDocHandler.process(DOMToDocHandler.java:37) at

Answers

Please, consider with the javax.xml.parsers.* JAXP package documentation.

Since SAX is object-oriented, the class providing for this serialization should implement the following SAX interfaces: EntityResolver, DTDHandler, ContentHandler and ErrorHandler. You can use the provided com.inqmy.lib.xml.util.SAXToOutputStreamHandler class. It implements org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.ErrorHandler, org.xml.sax.ext.DeclHandler and org.xml.sax.ext.LexixalHandler. To use this class, instantiate it through one of the provided constructors: SAXToOutputStreamHandler(String filename) – creates a new file and an XML, serialized to it. The file is closed at the end; SAXToOutputStreamHandler(OutputStream stream) – the XML is serialized to this stream, which is not closed at the end; SAXToOutputStreamHandler(Writer writer) – the XML is serialized to this Writer, which is not closed at the end. Example:

SAXToOutputStreamHandler handler = new SAXToOutputStreamHandler(“d:/temp/xml.out”); SAXParser sax = new SAXParser(); sax.setContentHandler(handler); handler.parse(“d:/temp/data.xml”);

Using JAXP 1.1 cannot easily perform this process. There is a class, which encapsulates the usage of our XPathProcessor as a stand-alone class, leaving the user distanced from the implementation. This class is very useful and provides a great functionality, which can be extended including any other suggestion. Class:com.inqmy.lib.xml.xsl.xpath.XpathMatcher


86/271

Constructor: XPathMatcher(String filename) throws FileNotFoundException, XpathException. This constructs a new XPathMatcher object, and initializes it with the specified file. If the file cannot be found then a FileNotFoundException is thrown. If there is any other error then an XPathException (com.inqmy.lib.xml.xsl.xpath.XPathException) is thrown. Also this exception is thrown when invoking the XML through any other method. Methods: init(String filename) – initializes an existing XPathMatcher instance. match(String query) – matches this query with the current context (by default, this is the root node) and returns true or false. An XnodeSet result – returns false if the node set is empty, else true. An XString result – returns false if the string is empty, else true. An XNumber result – returns false if the number is 0, else true. An XBoolean result – it is clear.

Advanced Use

The following methods provide advanced functionality. To use them, check javadoc (Java code documentation) first, to understand the class purposes.

• process(String query) – processes this query and returns a XObject. See the javadoc for more details.

• setContext(String query) - sets a current context. For example "/" sets the root node context, "/table" sets the first table node context, "/table[name = 'Bob']" sets the first table node context, which has 'name' child with 'Bob' value. In this case you can set the current context to any node and then to match the query, using this context.

• setContextNode(int node) – changes the context Node – see DTM and XpathContext.

• setContextSize(int node) - changes the context size. • setContextPosition(int pos) – changes the context position.

4. You have several packages in your classpath, which include the org.xml.sax

or org.w3c.dom, interfaces and the classloader loaded the older version. This usually happens when you try to use Apache (Tomcat) and SAP J2EE Engine. In this case you have either to move SAP J2EE Engine in front of apaches (xerces.jar, xalan.jar) in the classpath, to remove the other parser (it might be any other), or just to download new interfaces (for example 1.4.3 version of Xerces)


87/271

References

W3C Recommendation "XML Schema Part 1: Structures", Henry S. Thompson, David Beech, Murray Maloney, Noah Mendelsohn, 2 May 2001. (See http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/.)

W3C Recommendation "XML Schema Part 2: Datatypes", Paul V. Biron, Ashok Malhotra, 2 May 2001. (See http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/.)

W3C Recommendation "Namespaces in XML", Tim Bray, Dave Hollander, Andrew Layman, 14 January 1999. (See http://www.w3.org/TR/1999/REC-xml-names-19990114/.)

W3C Recommendation "Extensible Markup Language (XML) 1.0 (Second Edition)", Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, 6 October 2000. (See http://www.w3.org/TR/2000/REC-xml-20001006/.)

Java API for XML Parsing - http://java.sun.com/xml/jaxp/index.html

DOM 2 Specification - http://www.w3.org/DOM/


88/271

Chapter 4 J2EE Examples

• Market Summary Example

• CD Collection Example

• Statistical Calculator Example


89/271

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

• 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 bean and a Java file (YahooFinanceWebContent.java).


90/271

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

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 J2EE Engine memory. The <jsp:useBean> tag


91/271

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


92/271

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.

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

When the entity bean is started, the following methods are executed in the FacadeBean:

Method Description


93/271

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.

Container-Managed Entity Bean

The container-managed entity bean 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 bean with pre-allocated database connections in a connection pool.

Stateless Session Bean

The stateless session bean 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


94/271

YahooFinanceWebContent.java to open a URL connection to the 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.

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:


95/271

Mappings Tab

Setting the Environment Properties

The YahooFinance stateless session bean 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 bean 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 >

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:


96/271

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.


97/271

Storage Tab

EJB References in the WAR

To find the enterprise beans inside the FacadeBean Java code, there must be a mechanism to pinpoint each enterprise bean in the J2EE Engine’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 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


98/271

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 enterprise bean in the J2EE Engine JNDI context must be specified in the “Reference Name” field.

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

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 the J2EE Engine 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:


99/271

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

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→Element View. Select Services→dbpool→Application Node from the Visual Administrator left-hand pane. From the right-hand pane, choose the “Runtime” tab.


100/271

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 (Visual Administrator) Parameter Name Parameter Value

Driver com.inet.tds.TdsDriver Pool Name stkdata Database URL jdbc:inetdae:localhost?database=sample&sql7=true 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 user ID and password are valid


101/271

DBPool Runtime Tab

Finishing the Deployment Process

In the Deploy Tool choose “Deployer”. Select the MarketSummaryEAR.ear→MarketSummaryJAR.jar→MarketSummaryCMEntityBean node from the left-hand pane. Choose “Storage” from the right-hand pane. Enter the storage related data in the corresponding fields.


102/271

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.


103/271

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

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.


104/271

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

bean

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


105/271

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

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

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.


106/271

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 entity enterprise bean 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.

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.


107/271

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.


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)


108/271

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:

<%@ 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:


109/271

<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 (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>


110/271

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


111/271

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.

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.


112/271

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.


113/271

Chapter 5 Developers Tasks

• Configuring JBuilder Plug-in for Application Deployment and Debugging

• Lookup resources over the JNDI


114/271

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:

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.


115/271

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.

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.


116/271

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.


117/271

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 J2EE Engine 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.PortableRemoteObjectProxy -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


118/271

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 J2EE Engine, 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:


119/271

SAP J2EE Engine Application Deployment

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

Deploy Tool

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


120/271

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:

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.


121/271

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.

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→Application Node→Services→servlet_jsp from the 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 the JSPs on J2EE Engine 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.


122/271

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


123/271

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"); // 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]);


124/271

} } 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 application 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 an application node restart, the objects are erased.

Typically, objects are global. There are no 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 an application node. An example is provided below:

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


125/271

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

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


126/271

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


127/271

Chapter 6 Services Guide


128/271

Overview

Services in SAP J2EE Engine are divided into two groups – core and additional. Core services are part of the system kernel, as they help the system function. The additional services use the core modules to provide specific 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 the 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 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.


129/271

Admin Service

Overview

The 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 cluster node 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 cluster and information about all 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

• 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


130/271

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

• 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


131/271

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

• 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


132/271

• stopLevelCheck() – this method stops performing checks for the log level of the logs to be retrieved

• free() – releases all file references and pointers

public AdminServiceManager getAdminServiceManager(AdminCallback ac)

This method returns AdminServiceManager interface implementation, which provides for information and administration of all services and monitoring of the whole cluster. 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) – invoked when a specific service has changed its status

• updatedServiceDescriptor(String sName, int serverID, DeployedServiceDescriptor dsd) – invoked when a specific service descriptor is updated

• updatedServiceProperties(String sName, int serverID, Properties props) – invoked when a specific service property is updated

• addedServer(int serverID, String name) – invoked when an application node is added

• removedServer(int serverID, String name) – invoked when an application node is removed

• addedService(String sName, int serverID, String serverName) – invoked when a service is added

• removedService(String sName, int serverID, String serverName) – invoked when a service is removed

• updatedManagerProperties(String managerName, int serverID, Properties props) – invoked when the specific manager properties are changed

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

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


133/271

• 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 application node status:

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

application node managers and services are loaded successfully, and confirms that the J2EE Engine 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:

• 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]); } }


134/271

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

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


135/271

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 J2EE Engine.

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:

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:


136/271

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


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

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

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.


137/271

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

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.


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

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

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


138/271

additional properties are null, this method acts like the runClient() method, without additional properties in the argument list.


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 bean. 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:

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


139/271

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 bean. 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™.


140/271

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 application 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, DBMS Service runs on two types of cluster elements – state controllers and application nodes. The state controller serves as a single, central, persistent data storage in the cluster and does not handle client requests. It also holds information about the whole cluster and the participating nodes. An SAP J2EE Engine cluster has at least one and at most two state controllers. The second state controller contains the same data as the main one and is used as a backup in case of failure of the main state controller. Typically, the backup state controller is installed on another physical machine to prevent cluster crashes in case of hardware problems.

Note: The type of the cluster element is specified in the ClusterElementType property of the Cluster Manager. For more information on this property, refer to the Cluster Manager section of the Administration Manual.

The 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 application nodes in the cluster, and then, commits or rollbacks the transaction. The synchronization between the application nodes when committing a distributed transaction avoids lost or overwritten data.

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.


141/271

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.

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


142/271

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

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

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


public int getOpenConnections(String poolName) throws RemoteException

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

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

connections is returned • Return values

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


public int getFreeConnections(String poolName) throws RemoteException

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

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


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



143/271

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:

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


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 o int connID – the ID of the connection to be destroyed

• Exceptions


144/271


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


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

database

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



database


145/271

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



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:

• 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. • Exceptions


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


146/271

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


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



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


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


147/271

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. • Exceptions


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 • 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


148/271

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


149/271

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 application nodes in the 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 application nodes or, if the servers are not specified, on all containers in all application nodes 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 application nodes:

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

which points to the EAR 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


150/271

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

This method deploys the components found in the archive file to the specified container:

• Arguments o String archiveFile – the file that is to be deployed o String containerName – the name of the relevant container where the

file is to be deployed o String[] remoteSupport – the remote support for these components o Properties props – the specification used (J2EE_1_3 or J2EE_1_2);


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


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

on the J2EE Engine, 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 o java.rmi.RemoteException – thrown if some of the application

components cannot be removed


151/271

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 application nodes 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 application nodes.

• 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 application node. All applications on all registered containers are listed if the container name is null. All application nodes 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 application nodes 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

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 application node. If containerName is null, all components for the specific application on all registered containers are listed. If serverNames is null, the elements of all application nodes 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 application nodes 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 application nodes.

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


152/271

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

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


153/271

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.

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

• Exceptions o RemoteException – thrown when abnormal conditions occur, or when

there is a remote problem during the stopping process

public void startApplication(String applicationName) throws RemoteException

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

• Arguments o String applicationName – the name of the application to be 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


154/271

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

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 J2EE Engine:

• 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


155/271

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

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

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.


156/271

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.


157/271

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 J2EE Engine.

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 J2EE Engine • Exceptions

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

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



158/271

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 o RemoteException – thrown if there are communication-related errors

during a remote function call, or other error events

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


public void remove(String adapterName) throws RemoteException

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

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

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

during a remote function call, or other error events

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.


159/271

EJB1.1 Service

Overview

SAP J2EE Engine EJB1.1 Service manages and provides an environment for the enterprise beans deployed on the J2EE Engine. It is based on the EJB architecture for distributed computing, and implements the EJB1.1 specification fully.

The basic characteristics of enterprise beans are:

• Each bean 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 class. Therefore,

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

The EJB container is the environment where the beans are deployed and it provides access to the home interfaces of the beans.

When a bean, servlet, JSP, or application client needs to perform a lookup of the home interface of an enterprise bean, an EJB reference must be defined in the deployment descriptor of the component, which will perform the lookup. The code segment listed below illustrates how to perform the lookup:

Context initialContext = new InitialContext(); TestHome testHome = (TestHome)javax.rmi.PortableRemoteObject.narrow( initialContext.lookup(“java:comp/env/ejb/test”), TestHome.class);

The home interface of the bean is bound in the naming system using the bean’s name (ejb-name). Therefore, the SAP J2EE Engine EJB1.1 Service does not support multiple beans sharing the same name included in one or different applications. If a bean needs to be accessed by an RMI client, the client JAR of the application, which can be obtained from the Deploy Tool, must be included in the client classpath.

The deployment of container-managed persistent beans is performed using an additional XML file. It defines the Object-Relational mapping of the beans (that is, the mapping between the persistent fields of the bean and the corresponding table columns in the 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.


160/271

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.

161/271

EJB2.0 Service

Overview

The EJB2.0 Service implements Enterprise JavaBeans™ Specification, Version 2.0, which is part of the J2EE 1.3. Specification. However, EJB2.0 is only partly implemented in SAP J2EE Engine 6.20 and this service should be used only for test scenarios.

A message-driven bean example is included in the Message-Driven Bean Deploy Guide chapter in this manual.

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 enterprise beans.

inqmy-ejb.xml has the following format:

 <!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*)> <!-- Destination-name element specifies the name of the Destination that is used by the container to register a particular message- driven bean as listener.

162/271

--> <!ELEMENT destination-name (#PCDATA)>  <!ELEMENT ejb-name (#PCDATA)>  <!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?)>

163/271

<!ELEMENT res-name (#PCDATA)>  <!ELEMENT res-link (#PCDATA)>  <!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)>

164/271

<!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*)>  <!ELEMENT security-role (#PCDATA)> <!-- User element specifies user to which particular security role is mapped.

165/271

--> <!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*)>  <!ELEMENT method-param (#PCDATA)>  <!ELEMENT persistent-data-properties (load-strategy?,properties?)>


166/271

<!ELEMENT load-strategy (#PCDATA)>


167/271

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 J2EE Engine 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 J2EE Engine 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


public void openRead() throws IOException

This method opens a file for reading:



168/271

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 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 you access the SAP J2EE Engine remotely.

• 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 that the file path be relative to the J2EE Engine directory.

• Return values o RemoteFile – returns the remote file


169/271

• 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

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 int getBufferSize()

This method gets the buffer size of the local file for transferring data to the remote one.

• Return values o Returns an integer value that specifies the buffer size

public void setBufferSize(int size)

This method sets the buffer size of the local file for transferring data to the remote one:


170/271

• Arguments o int size – an integer argument that specifies the 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 J2EE Engine using the name specified in the RemoteFIle constructor.

Example

To run the example, the full path to the client JAR on the J2EE Engine 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.


171/271

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 J2EE Engine 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 the J2EE Engine. The J2EE Engine responds with a status line, including the message’s protocol version, and a success or error code, followed by a MIME-like message containing J2EE Engine information, entity meta information, 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.

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.


172/271

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

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.


173/271

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.


174/271

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 application node implementations to reflect peculiarities of this communication. Communication Layer delivers the request in the proper format to the Execution System that 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.


175/271

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.


176/271

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

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

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


177/271

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.

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.


178/271

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


179/271

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


180/271

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

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, 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 Connection



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.

XAQueueConnectionFactory

An XAQueueConnectionFactory provides the same create options as a QueueConnectionFactory.


181/271

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 Connection



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 Connection



XATopicConnectionFactory

An XATopicConnectionFactory provides the same create options as TopicConnectionFactory.

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 Connection




182/271

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.

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


183/271

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:

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


184/271

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)

An implementation of the IAIK provider is used to run 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, w3c_http.jar or download them from http://jcewww.iaik.at/download/evaluation/index.php. To run the SSL and Keystore service run on the J2EE Engine, you have to deploy the required IAIK libraries:

• in the server console activate the deploy command group exsecute: add deploy

• exsecute the following command: changelib -u IAIKSecurity <path to each jar with ; as separator>

• make sure that the IAIK libraries are copied to the <SAP_J2EE_Engine_dispatcher>/additional-lib directory.

• make sure that the IAIK libraries are copied to the <state>/additional-lib directory for the instance that have the state controller.

• make sure the cluster is stopped • for the dispatcher delete the

<SAP_J2EE_Engine_dispatcher>/service/ssl/work/socketConfiguration.properties file

• using the configTool ocnfigure the startup mode for keystore and SSL Services to ALWAYS for the application nodes and the dispatchers. Also configure the keystore to have ALWAYS start-up mode on the state controllers

• Apply the changes in the conifgTool • Start the cluster

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.


185/271

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.

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.


186/271

• 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

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


187/271

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.


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


188/271

LogObject

public void setFromFile(String file)

Sets the source file for the LogObject.

• Arguments o String file – the name of the source file

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.


189/271

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 beans’ 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:

• 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 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 (enterprise beans

for example) can be obtained from the Naming Service.

Interfaces



190/271

For information on how to use Naming Service functions, refer to Lookup Resources Over the JNDI in Developers Tasks section of this manual.


191/271

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


192/271

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


193/271

• 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

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 RemoteServiceReference interface by the information received from the lookup of the Security Service performed in the


194/271

naming. Actual access to the remote interface of the service is gained using the getServiceInterface() method.


195/271

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 beans deployed on SAP J2EE Engine. In this way, results obtained from processing the beans’ 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 application nodes 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.


196/271

Security Service

Overview

Security Service provides the SAP J2EE Engine security. Basically, the Security Service consists of RemoteSecurity interface and the following main modules, located in the com.inqmy.services.security.remote package:

• Remote Security interface (RemoteSecurity.java) • User Manager (RemoteUserManager.java) • Resource Manager (RemoteResourceManager.java) • Protection Domain Manager (RemoteProtectionDomainManager.java) • JAAS • Login System (RemoteLogin.java) • SAP Integration Manager (RemoteSAPIntegrationManager.java)

Interfaces

Remote Security

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


public RemoteProtectionDomainManager getRemoteProtectionDomainManager() throws java.rmi.RemoteException

• Return values o An interface to the protection domain module



197/271

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


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.


198/271

User Manager

RemoteUserManager interface 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 J2EE Engine security-sensitive resources. Access can be granted or denied only by the administrator of the J2EE Engine (“Administrator”). The administrator has full rights to administrate the system resources, to create, remove, grant or deny access to 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 J2EE Engine in this group. Administrative rights can be granted to any user, no matter where the user was created.

o “guests” – contains a default user “Guest” with default password “guest” o “external” – contains users using the JAAS protocol to log in to the J2EE

Engine

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



199/271

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

• 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

o Randomly generated password • Exceptions

o SecurityException


200/271

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.


ignore this parameter if they do not maintain groups and users. o name – the name of the user or the group o parent – the new parent group of 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 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


remove users, or no user with such name exists


201/271

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


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

public void ungroupUser(boolean user, String name, String parent) throws SecurityException

This removes a user or a group from a parent group:


ignore this parameter if they do not maintain groups and users. o name – the name of the user or group o parent – the parent group of the user or the group


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:


ignore this parameter if they do not maintain groups and users. • Return values

o Enumeration of user or group names • Exceptions

o SecurityException – thrown if the caller is not granted permission

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


202/271

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

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

Resource Manager

The basic function of RemoteResourceManager is to handle and manage resources.

A resource is an abstract object. For example, it may represent an enterprise bean 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 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


203/271

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

• 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



204/271

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

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


205/271

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.

Remote Resource Handle

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.

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


206/271

o actionId – action identifier • Return values

o The name of the action

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:

• Arguments o instanceId – the instance identifier

• Return values o The name of the specified instance


207/271

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:

• 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


208/271


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


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.

Protection Domain Manager

RemoteProtectionDomainManager 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


209/271

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 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 J2EE Engine Security Service 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


210/271

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

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


211/271

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


212/271

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


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 J2EE Engine, 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.


213/271

Login System

The RemoteLogin in the Security Service enables different users to log on and log out from the J2EE Engine. A user logs on 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 J2EE Engine 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 J2EE Engine at any time.

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


214/271

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


215/271


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

RemoteSAPIntegrationManager 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 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



216/271

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

o java.rmi.RemoteException - if an error in the RMI layer occurs

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 of


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.


217/271

The following properties are recognized:

Key Description Default Value

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 J2EE Engine host name (same as in JCO) n/a sapbasis.sysnr SAP J2EE Engine instance number (same as in

JCO) n/a sapbasis.mshost Message server host name (same as in JCO) n/a sapbasis.r3name SAP J2EE Engine system ID (same as in JCO) n/a sapbasis.group SAP J2EE Engine 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 J2EE Engine (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

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


218/271

o java.lang.SecurityException - if the JAAS configuration could not be determined

o java.rmi.RemoteException - if an error in the RMI layer occurs

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 of


public void startSapSecurity() throws java.lang.SecurityException, java.rmi.RemoteException

This retrieves the current configuration from the DBMS, and (re-)starts SAP security. If the initial startup was successful, the configuration is automatically started at each following J2EE Engine restart.

• Exceptions o java.lang.SecurityException - if SAP security could not be started o java.rmi.RemoteException - if an error in the RMI layer occurs

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 when the J2EE Engine 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


219/271

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.

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 {


220/271

// 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; }

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

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:


221/271

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

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


222/271

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.


223/271

Servlets_jsp Service

Overview

Servlets_jsp Service represents both a container that manages servlets and an engine that uses JSP (JavaServer 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.


224/271

Shell Service

Overview

SAP J2EE Engine Shell Service provides Shell commands to control the running processes in the J2EE Engine and administrate the cluster components using the Console Administrator tool or for remote administration – Telnet.

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


225/271

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

• 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


226/271

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


227/271

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, w3c_http.jar or download them from http://jcewww.iaik.at/download/evaluation/index.php. To run the SSL and Keystore service run on the J2EE Engine, you have to deploy the required IAIK libraries:

• in the server console activate the deploy command group exsecute: add deploy

• exsecute the following command: changelib -u IAIKSecurity <path to each jar with ; as separator>

• make sure that the IAIK libraries are copied to the <SAP_J2EE_Engine_dispatcher>/additional-lib directory.

• make sure that the IAIK libraries are copied to the <state>/additional-lib directory for the instance that have the state controller.

• make sure the cluster is stopped • for the dispatcher delete the

<SAP_J2EE_Engine_dispatcher>/service/ssl/work/socketConfiguration.properties file

• using the configTool ocnfigure the startup mode for keystore and SSL Services to ALWAYS for the application nodes and the dispatchers. Also configure the keystore to have ALWAYS start-up mode on the state controllers

• Apply the changes in the conifgTool • Start the cluster

Start Keystore and SSL Services on all cluster nodes. The Keystore Service must be started first.

Example:

Start the SAP J2EE Engine.

Try to access the localhost by executing the following text in a browser:

https://localhost/

You cannot use this service remotely. For more information refer, to the Administration Manual.


228/271

Interfaces



229/271

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 all cluster 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 J2EE Engine listens for a 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 J2EE Engine.

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.


230/271

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 enterprise beans can use this interface.

A list of methods is provided below.

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


231/271

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


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:


not associated with a transaction o SystemException – thrown if an unexpected error occurs


232/271

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. • Exceptions


TransactionManager Interface

The javax.transaction.TransactionManager interface is implemented in Transaction Service to enable the J2EE Engine to manage the transaction demarcation of the current application.

A list of methods is provided below.

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:


233/271

• Return value o Returns the transaction status. If no transaction is associated with the

current thread, this method returns the Status.NoTransaction value. • Exceptions


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:


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:


not associated with a transaction


234/271


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


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.

• Exceptions o SystemException – thrown if an unexpected error occurs

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 J2EE Engine 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.

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


235/271

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


236/271

Chapter 7 Developing Third-Party Visualizations

of SAP J2EE Engine Tools • Overview

• Config Tool

• SAP J2EE Engine Installation and Uninstallation Programs


237/271

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.


238/271

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

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.


239/271

<!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 application node to be added.

<!ATTLIST make-new-server name CDATA #REQUIRED> – specifies the name of the added application node.

<!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 application 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.

<!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 J2EE Engine), automatic (the service is started on demand of a client


240/271

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.

<!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>


241/271

</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/ 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>


242/271

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 J2EE Engine installation as 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.

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.


243/271

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 J2EE Engine configuration. This file is 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


244/271

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 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 J2EE Engine version from which the upgrading process can be performed.

<!ELEMENT version-max (#PCDATA)> – specifies the maximum J2EE Engine 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.

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


245/271

<!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, state, 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.

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>


246/271

<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> <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?, create-dialog-instance?, installed-groups?)> <!ELEMENT user-name (#PCDATA)>


247/271

<!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 create-dialog-instance (#PCDATA)> <!ATTLIST create-dialog-instance connect-host CDATA #REQUIRED connect-port CDATA #REQUIRED backup-connect-host CDATA #IMPLIED backup-connect-port CDATA #IMPLIED backup-state-controller CDATA #REQUIRED> <!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?, create-dialog-instance?, installed-groups?)> – this is the root element. It must have the name install.

<!ELEMENT user-name (#PCDATA)> – specifies a valid user name.

<!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, state controller, and “alone” configuration running.

<!ELEMENT create-dialog-instance (#PCDATA)> – specifies if a dialog instance is to be installed. The instance consists of a dispatcher, an application node, and an optional backup state controller.

<!ATTLIST create-dialog-instance connect-host CDATA #REQUIRED connect-port CDATA #REQUIRED backup-connect-host CDATA #IMPLIED backup-connect-port CDATA #IMPLIED backup-state-controller CDATA #REQUIRED> – describes a dialog instance. connect-host and connect-port define the host and port for connection to the state controller of the cluster. If a backup state controller exists, its host and port are specified in backup-connect-host and backup-connect-port respectively. backup-state-controller takes a boolean value (true or false) to indicate if a backup state controller is to be installed in the dialog instance as well.


248/271

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

<!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 </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 J2EE Engine administration at runtime." group-dir="admin/" name="admin" size="6877934"> <properties> </properties> </install-group> <install-group description="Installs an application node of SAP J2EE Engine cluster. To create a working cluster, you must include the Dispatcher and State component groups, too. Select the Properties button (applied to the Visual Installation only) to modify the Application node initial properties." group-dir="cluster/server/" name="server" size="9440429"> <properties> <property key="JoinPort" value="2078">


249/271

</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)> <!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.


250/271

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

<!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"


251/271

os="Windows;Unix;Solaris;Netware"> <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.

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


252/271

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>


253/271

Chapter 8 Message-Driven Bean Example


254/271

Overview

About the Example

Note: The EJB 2.0 standard is not fully supported on the J2EE Engine. That is why you can use this example, and message-driven beans at all, only for testing and preview purposes. Note that this example might not work in some versions of the SAP J2EE Engine, because of a bug in the JMS Service.

Location

The message-driven bean (MDB) example is located under <J2EE_Enigne_install_dir>/docs/examples/MDB directory. This folder has the following directories:

• classes – contains the Java classes of the example. • deploy – contains an already generated mdb_session.ear file that you can

deploy on the J2EE Engine. • lib – in this directory you have to manually put all required library files. • scripts – contains the script files that actually runs the example. • src – contains the source files of the example. • xml – contains the sources of the XML files used in the example.

Scenario

In this MDB example, a test class sends a message to a queue. On this queue the MDB listens and then sends a call to a stateless session bean for processing. Then the MDB prints the result on the application node command line.

Note: If you use the J2EE Engine JMS Service or external JMS servers, which support JNDI, you must use the required type of connection factory.

Description of the Enterprise Bean

There are two XML descriptor files in the bean’s JAR:

• ejb-jar.xml The standard deployment descriptor, which Data Type Definition (DTD) is defined in the EJB2.0 Specification.

• Inqmy-ejb.xml The deployment descriptor specific for the EJB 2.0 container on the J2EE Engine. It contains the following tags: o <connection-factory-name>

The name of the Connection Factory that the bean will use. o <container-size>

The initial container size. o <load-factor>

The factor for increasing the container size, if required. o <property-name> and <property-value>

Additional properties that helps the container to get a Connection object from the Messaging System and create a new Session (that is you must


255/271

set clientID property in the XML descriptor if you want the JMS connection to has a client identifier).

Running the Example

Steps to Run the Example

• Adjust the path of the mdb_session.ear file in the dep.scr file. For example: deploy -j2eeVersion 1.3 C:\SAP_J2EEngine6.20\docs\examples\MDB\deploy\mdb_session.ear

• Include the following libraries to the specified location:

For cluster installation:

o In <J2EE_Engine_install_dir>cluster/server/additional-lib include jms.jar. o In <J2EE_Engine_install_dir>cluster/server/additional-lib include

ejb20.jar. o In <J2EE_Engine_install_dir>/tools/lib include client.jar.

For standalone installation:

o In <J2EE_Engine_install_dir>alone/additional-lib include jms.jar. o In <J2EE_Engine_install_dir>alone/additional-lib include ejb20.jar. o In <J2EE_Engine_install_dir>/tools/lib include client.jar.

• Execute the scripts from the scripts directory of the MDB example. Use the following command line: run <name of the script>

The following scripts are provided:

o all.scr – runs all the other scripts. o dep.scr – deploys the message-driven bean EAR file. o factory.scr – starts the command, which creates the required

connection factories. o serv.scr – starts the EJB service.

Basically, you need to run the all.scr file. It performs the following:

• Starts the ejb20 services on the J2EE Engine using the following command line: startservice <clusterID> ejb20

Note: The cluster ID of the server element can be taken by executing the lsc command on the server console - the first node in the list is the one you are executing the command on. For standalone server the server ID should be specified (it is 2000 by default).

• Adds the commands from the ejb20 group - in particular make_jms_connectionFactory

• Executes the following command: make_jms_connectionFactory -factoryName SAPConnectionFactory -namingEnable true -linkFactoryName QueueConnectionFactory -initialContextFactory


256/271

com.inqmy.services.jndi.InitialContextFactoryImpl -providerUrl localhost -securityPrincipal Administrator -securityCredentials

• Adds commands from the deploy group so that you are able to execute deploy command: add deploy

• Deploy the application with -j2eeVersion 1.3 option deploy -j2eeVersion 1.3 <path to the ear file>

Creating a New Connection Factory

The J2EE Engine JMS Service supports the following connection factories:

• XAQueueConnectionFactory • XATopicConnectionFactory • QueueConnectionFactory • TopicConnectionFactory

The JNDI Context of the factory is jmsFactories.

To create a new Connection Factory, use the following on the command line:

add ejb20 make_jms_connectionFactory factoryName <name of the factory you want to create>

Also you may have to define the other properties for the command. Such newly generated JMS Connection Factory can be either with or without a JMS Provider. If a JMS Provider is specified, then from the following list of properties, the onse denoted by “*” must be specified (for example for SonicMQ JMS Provider):

• [ - namingEnable] - true if JMS Provider provides the Naming Context, false otherwise.

• * [ - linkFactoryName] - Specifies the name of the remote JMS server factory. Using this name the Naming system performs the remote lookup.

• * [ - initialContextFactory] – Specifies the INITIAL_CONTEXT_FACTORY of the JMS Provider's naming.

• * [ - providerUrl] - Specifies the PROVIDER_URL of the JMS provider's naming.

• * [ - securityPrincipal] – Specifies the SECURITY_PRINCIPAL of the JMS provider's naming.

• * [ - securityCredentials] – Specifies the SECURITY_CREDENTIALS of the JMS provider's naming.

• [ - objectFactoryName] – Specifies the name of the JMS provider's objectFactory.

• [ - className] – Specifies the the class name of the connection factory. • [ - propertyName] – Specifies the the name of the property for the

Connection Factory. • [ - propertyValue] – Specifies the the value of a property for the

Connection Factory.


257/271

Running the Connection Factory using SonicMQ as JMS Provider

Steps to Take

To run the Connection Factory using SonicMQ as JMS Provider, you have to exsecute the following on the server command line:

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

Additional Settings

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

library sonic client.jar … reference sonic jms

In the 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>

To start the EJB20 Service automatically, edit the runtime.xml:

<startup-mode> # must be set to “always” manual

</startup-mode>

Start the EJB20 Service.


258/271

Sending Messages Between Application and External JMS Server

To send messages between an application and external JMS server (other then the J2EE Engine), you have to define 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.

Where “sonic” is the name of the library defined in library.txt.

See also:

• Administration Manual → Configuration of Additional Libraries


259/271

Chapter 9 IqLib,

Introduction to SAP Java Data Structures and Algorithms Library

• Overview

• Introduction


260/271

Overview

IqLib is a data structures and algorithms class library designed to provide fast and professional Java development. Along with the basic data structures, IqLib also provides advanced solutions, as well as efficient algorithms for processing them.

Features

IqLib offers an alternative of Sun’s JDK, providing improved implementation of data structures that JDK includes and enhancing its functions significantly, with some advanced concepts:

• Data structures - IqLib also provides a set of data structures that includes both basic structures such as arrays and lists, and complex data structures, such as binary search trees, AVL Search trees, randomized search trees (treaps), hashtables, sets, and so on.

• Algorithms - IqLib also provides effective algorithms, which can be applied to each data structure using iterators

• Concurrency and synchronization primitives - SAP Java class library introduces solutions to problems with concurrency and synchronization of data processing. IqLib provides monitors, semaphores, barriers, lockers, and task executors that enable concurrent and parallel programming.

In addition, IqLib provides adapters to JDK so that both libraries can be used together.

Benefits of Using IqLib

IqLib is designed to offer solutions to three major problems that developers may encounter:

• Insufficient knowledge of complex data structures and algorithms developers are often familiar only with implementing simple data structures and algorithms that usually do not provide optimal performance. With IqLib even programmers that are inexperienced in Java can use more advanced and efficient solutions.

• Long development time - implementing complex data structures and algorithms takes time and slows down the development process. IqLib speeds up development, because SAP Java class library provides ready-to-use classes.

• Bugs - testing and debugging code is a difficult and time-consuming procedure. IqLib helps reduce the number of bugs by providing tested and reliable solutions.


261/271

Goals

IqLib provides Java developers with a useful set of efficient solutions. It achieves the following design goals:

• Easy usage - IqLib provides ease of use even for developers who are not experienced in Java

• Reusability - IqLib solutions can be reused in multiple programs and for a number of purposes. It saves the effort of implementing similar classes several times.

• Efficiency and high performance - IqLib solutions provide maximum efficiency and are optimized for high performance

• Good structure and design - IqLib structure and design has been enhanced to make the library consistent, efficient and easy to use

• Extensibility - IqLib functions can be extended by adding data structures and algorithms

• Flexibility - a single algorithm can be applied to various data structures

• Reliability and stability - these solutions are tested thoroughly to prove they are stable and reliable. In addition, each class is documented in detail.


262/271

Introduction

IqLib is a Java generic data structure, algorithm, and multithreading library used in SAP J2EE Engine. The problem domain on which IqLib is focused, is defined by Nicklaus Wirth’s remarkable formula about structure programming:

Programming = Algorithms + Data Structures,

When applied to OOP, this is modified to the following:

Programming = Data Structures + Algorithms,

In OOP, with multithreading this becomes:

Programming = Data Structures + Algorithms + Multithreading

This triad of problems forms the skeleton of object-oriented programming in a multithreaded environment. Since multithreading implies synchronization between threads, IqLib provides a number of synchronization mechanisms to enable concurrent programming.

Packages

IqLib consists of the following packages:

• Data Structures com.inqmy.lib.util.*

• Algorithms com.inqmy.lib.util.algorithms.*

• Multithreading & Synchronization com.inqmy.lib.util.synch.*

Note: This structure presents the core part of IqLib, which is included in v.1.0 and provides basic functions. Future versions will provide advanced solutions.

Key Concepts

IqLib solutions are built on the basis of the following key concepts:

• Element - in IqLib, this corresponds to java.lang.Object in JDK

• Item - this is a wrapper of the element that enables you to store it in data structures. Item is the object that is used to create references between elements. It also provides for their cloning, both deep and shallow.

• Enumeration - provides a “snapshot” or static view of elements. It can be used to obtain successive elements from a series of elements.

• Iterator - a dynamic view of elements. Iterators are the interface between data


263/271

structures and algorithms, because algorithms are applied over iterators but affect data structures.

• Comparator - presents the binary relation between elements. It can be used to sort elements in particular data structures that require total ordering.

• Data Structure - collections of elements. Each data structure imposes a specific organization of elements that is used for the efficient application of algorithms.

• Algorithms - sets of actions performed using iterators over data structures. They can either modify a data structure (for example, algorithms for sorting, adding, and removing elements) or simply find a particular element without changing the actual data structure (search algorithms). The use of iterators provides applicability of algorithms over various data structures.

Data Structures

JDK-Like Data Structures

IqLib is designed to be JDK-like to provide Java developers with a library in a style familiar to them, thereby making IqLib usage easier and less time consuming. However, IqLib enhances JDK functions significantly.

While JDK data structures (HashMap, Set, Vector, and so on) contain Objects only, IqLib contains similar data structures for native types:

• HashMapObjectObject, HashMapIntObject, HashMapIntInt, and so on • Set. SetInt, SetLong, and so on • ArrayObject, ArrayInt, ArrayLong, and so on • Stack, Deque, Queue, as well as corresponding wait structures (WaitQueue,

WaitStack, WaitDeque). The implementation of these structures blocks a thread that waits to add or delete an element as long as the data structure is full.

IqLib data structure implementations reduce memory usage drastically, thereby providing better performance.

In addition, algorithms can be applied over JDK structures using the adapters provided for them.

Note: At present, algorithms cannot be applied over structures for data types other than Object. This will be provided in a future release of IqLib.

IqLib offers a number of enhancements to JDK functions. For example, IqLib items use ItemAdapters to speed up performance. Limits could be defined for various data structures, iterators and enumerations to apply algorithms over the structures, and the algorithms that are provided present effective solutions and save time. One of the important features of IqLib is that it provides for “deep clone.” Deep clone copies the entire structure of he object being cloned, while “shallow clone” shares the instance variables between the clone and the original.


264/271

Additional Data Structures

In addition to JDK-like data structures, IqLib provides implementations of advances data structures – lists and trees.

Lists

List is a dynamic ordered data structure that can consist of n elements. Dynamic implies that the value of n might change. The nodes of a list have linear order based on their position in the data structure. The first element is called head and the last one is called tail. IqLib includes the following implementations of lists:

Linked List

Linked list is a data structure that connects its elements using pointers. Each node of a linked list contains two fields: data (which holds the list element), and next (which stores the pointer to the next element). The next field of the last node of the list is NULL.

NULL

Linked List

IqLib provides implementation of stack and queue as linked lists. Stack is a “Last In First Out” (LIFO) dynamic set, while queue is a “First In First Out” (FIFO) dynamic set.

Doubly Linked List

The nodes of the doubly linked list contain three fields: data, previous, and next. The previous field stores a pointer to the preceding element. The next field holds a pointer to the following element. For this data structure, the previous element reference of the head node and the next element reference of the tail node are NULL.

NULL NULL

Doubly Linked List

IqLib presents an implementation of doubly ended queue (deque). Deque is a data structure that combines the properties of a stack and a queue. Elements can be added to, or deleted from, both the head and the tail of the deque.

Trees

Trees are defined as connected acyclic graphs - the root node of the tree is the only one that has no parent nodes. The nodes that do not have children are called leafs or external nodes; all nodes that have child nodes (that is, the parent nodes) are also called internal. Trees are ordered or unordered. In an ordered tree, the children of a node have a specific linear ordering, and can be referred to as first node, second node, and so on. This cannot be done for an unordered tree.

A specific type of ordered tree is binary tree. These are ordered trees in which each node has zero, one, or two children. The first and the second child of a node with two children are referred to as left and right child respectively. A binary tree is full when


265/271

each of its nodes is either a leaf, or has two children. A perfect binary tree is a full binary tree, in which all leaves are of the same depth. To obtain a complete binary tree, the right-most leaf of a perfect binary tree is removed.

IqLib provides implementations of the following types of tree data structures:

• Binary Search Tree • AVL Tree • Treap

For these data structures, the running time of search, insert, and delete procedures is proportional to the height of the tree considered. Asymptotic analyses of these data structures show that their running time for insert, delete or search algorithms is approximately O(log2N) – that is, their height is O(log2N) where N is the number of nodes.

Binary Search Tree

Binary search trees are organized as binary trees, for which the associated key value of the left child element is less than the key value of the parent node, and the key value of the right child element is greater than that of the parent. This type of data structure combines binary search possibilities with good performance for insert and delete algorithms. Although this type of data structure provides a fairly simple way to find, insert, or delete nodes, the optimal O(log2N) height is not guaranteed because binary search trees are not height balanced.

75

84

22 78

57

7321

> 75

> 78

< 75

< 22 > 22

< 73

Binary Search Tree

AVL Tree

AVL tree is a binary search tree that is strictly balanced – that is, the balance factor of each node is –1, 0, or 1. The balance factor of a node is computed by subtracting the height of its left subtree from the height of its right subtree. AVL trees provide for O(log2N) search time, although the running time of insert or delete algorithms is increased.

Treap

Randomised binary trees (treaps) are randomly balanced binary trees that prove to be even more efficient than AVL trees. The optimal algorithm running time (O(log2N)) is achieved for both search and change (insert or delete) procedures.


266/271

Threadsafe Versus Nonthreadsafe Data Structures

Since multithreading is a vital part of object-oriented programming, IqLib provides dual implementations of data structures: both threadsafe and nonthreadsafe.

Threadsafe (synchronized) implementation guarantees correctness but it is slower than non-threadsafe implementation. You should use nonthreadsafe implementation for better performance when access involves reading only.

Note: Future enhancements of IqLib will include differentiation between read and write operations for threadsafe data structures.

An example of threadsafe versus nonthreadsafe implementation is Set (nonthreadsafe) and ConcurrentSet (threadsafe).

Iterators

Iterators are the interface between data structures and algorithms. Through appropriate iterators, algorithms can be made reusable over various data structures.

IqLib provides four interfaces that have methods for changing the underlying data structures. These are:

• AddableIterator - the interface for iterators that are used to add elements to data structures

• InsertableIterator - the interface for iterators used to insert elements in data structures at the position to which the iterator points

• ChangableIterator - the interface for iterators that are used to change the element to which the iterator points

• RemovableIterator the interface for iterators that are used to remove the element to which the iterator points

All of the interfaces listed above extend the RootIterator interface, which provides iterators’ basic functions.

In addition, IqLib provides three more interfaces:

• ForwardIterator - this interface extends all of the interfaces mentioned above; AddableIterator, InsertableIterator, ChangableIterator, and RemovableIterator. It lets you browse data structures in a forward direction only.

• BidirectionalIterator - this interface extends ForwardIterator, but lets you browse the underlying data structure both backward and forward.

• RandomAccessIterator - this interface extends BidirectionalIterator and also provides two additional methods that return the current position of the iterator, and can point it at a randomly chosen position in the data structure


267/271

RootIterator

AddableIterator RemovableIterator

ForwardIterator

BidirectionalIterator

RandomAccessIterator

InsertableIterator ChangeableIterator

Algorithms

Algorithms are applied over iterators that provide access to the underlying data structure. In this way, data structures appear unified to algorithms, which can be reused many types over various types of data structures – that is, algorithms are generic.

IqLib includes two major types of algorithms: MutableAlgorithm and ImmutableAlgorithm. MutableAlgorithm abstract class is the parent class for all algorithms that modify the data structure - for example, CopyAlgorithms, RemoveAlgorithms, SortAlgorithms, and so on. ImmutableAlgorithm is the parent class for algorithms that do not involve changes in the data structure, such as FindAlgorithms, MatchAlgorithms, and so on.


268/271

Algorithms

ImmutableAlgorithm MutableAlgorithm

CopyAlgorithms

FillAlgorithms

RemoveAlgorithms

ReplaceAlgorithms

SortAlgorithms

TransformAlgorithms

CountAlgorithms

FindAlgorithms

ForEachAlgorithms

MatchAlgorithms

• CopyAlgorithms - contains algorithms to copy one iterator to another, insert elements to other iterators, and swap the elements of two iterators

• FillAlgorithms - generates elements in a data structure

• RemoveAlgorithms - removes elements from iterators

• ReplaceAlgorithms - replaces elements of iterators

• SortAlgorithms - contains algorithms to sort iterators

• TransformAlgorithms - transforms iterators by applying functions over them

• CountAlgorithms - counts the number of occurrences of an element in a data structure

• FindAlgorithms - contains algorithms to find an element in a data structure

• ForEachAlgorithms - applies UnaryFunction over elements in data structure

• MatchAlgorithms - tests for equality of iterators

Multithreading and Synchronization

Multithreaded environment imposes synchronization of the access to variables because all threads share single memory. IqLib provides a variety of mechanisms for synchronization, as well as a framework for parallel and serial task execution.

Synchronization is achieved using event listeners for all synchronization primitives. IqLib synchronized implementations support different types of thread scheduling:

• JVM - the standard Java Virtual Machine thread-scheduling scheme (random)


269/271

• First In First Out (FIFO) - in accordance with this scheme, threads continue with their work in the order in which they have been put in waiting queue

• Priority - threads are “awoken” in the order, defined by a priority that is assigned to them

• NON_INFINITY_READ - this scheme guarantees that threads can perform the write operation

• NON_INFINITY_WRITE - this scheme guarantees that threads can perform the read operation

Task execution framework enables you to build a graph of tasks to be executed simultaneously or consecutively.

IqLib also connects to thread pooling, thereby improving performance by using reusing treads.

Synchronization Mechanisms

IqLib offers implementations of four mechanisms for synchronization: semaphores, barriers, monitors, and read-write lockers.

Semaphore

Semaphore is used when the number of resources (items) is less than the number of threads that have to be associated with the items. To synchronize the access to the resources (items), the semaphore is initialized to the number of items available. Threads request an item and are associated to one as long as there are free items available. As each thread occupies an item, the number of available items is decremented by one. When there are no more resources available, the requesting threads wait until other threads release items.

A semaphore that is initialized to a single item is called mutex (mutual exclusive lock).

Another type of semaphore is countdown. If countdown is used, all threads wait until the value of 0 is reached.

Barrier

Barrier is an object that is initialized to a certain number of threads (T) it controls. Threads arrive at the “barrier” point at a specified phase of their work. When reaching the barrier, threads wait until all T threads finish their work and then continue their computations. In distributed computing, threads can exchange information at the barrier point.

Countdown can also be perceived as a one-time barrier, as it cannot be reset.


270/271

Barrier(2)

Barrier(3)

Thread 1 Thread 2 Thread 3

Thread 2Thread 1

Barrier

Monitor

Monitor is a standard JDK synchronization mechanism. It is a high-level synchronization primitive. The concept of monitor involves a single thread executing in the monitor at a time, while all other threads wait. When the thread that executes finishes its work, waiting threads can be signaled or broadcast to continue their work. If signaled (broadcast), a waiting thread is “re-activated” once the monitor becomes free.

Both monitors and semaphores are a proper solution of the “consumer-producer” problem, when one thread needs resources that are generated by another thread. The first thread does not execute until the second one has finished executing.

ReadWriteLocker

ReadWriteLocker is a synchronization mechanism, based on imposing read and write locks on resources. A single resource can be read-locked by multiple threads executing simultaneously, but you cannot impose other read or write locks on a resource that has already been locked for writing. Also, you cannot impose write locks on read-locked resources.

Task Framework

The IqLib concept of multithreading includes a framework for serial and parallel execution of tasks along with the various synchronization mechanisms. This framework lets you create a graph of tasks to be executed.

Task is a wrapper of Runnable object. It implies work to be executed. Task Executor is an object that supports a set of tasks and provides methods for their serial or parallel execution. Task Executor can connect to a Thread Manager or to a thread pool using TheadManagerConnector. It executes each task in a separate thread that could be assigned priority.


271/271

T hreadM anager T hreadM anagerC onnec to r

T askE xecu to r

taskP aralle l execu tion

task

task task

task

tasktask

task

Serial execution

iq L ib

Task Framework

Development Manual - archive.sap.com

Documents

Transcript of Development Manual - archive.sap.com