Keywords: |Released by:|Signature:|

ACS Java Component Programming Tutorial

Programmer's Manual

Heiko Sommer (hsommer@eso.org)

ESO

Change Record

Table Of Contents
1 Introduction
1.1 Purpose and Scope of the Document
1.2 Abbreviations
1.3 References
2 What you need
2.1 Getting Eclipse IDE
2.2 Getting the source code
2.3 Compiling and running the examples
2.3.1 Make
2.3.2 Run
2.3.3 Using an IDE (Debugging!)
2.3.4 Windows development with limitations
2.3.5 Logging
3 Designing the Components
4 Creating the HelloDemo Component
4.1 IDL
4.2 Component Implementation
5 Creating the XmlComponent Component
5.1 XML entity classes
5.1.1 Overview
5.1.2 Designing entity schemas
5.1.3 Compiling entity schemas
5.2 IDL
5.2.1 Using XML schema types in IDL – general idea
5.2.2 XmlComponent.idl
5.2.3 Compiling IDL
5.3 Component implementation
6 Component Helper Classes
7 Configuration Database
8 Clients
8.1 Generic Client: ObjectExplorer
8.2 Client Component
8.3 JUnit Test Client

Introduction

Purpose and Scope of the Document

The purpose of this document is to give a practical introduction to writing Java components for ALMA software, using the ACS container/component framework. You should have read the section on Technical Architecture in [<ac:structured-macro ac:name="anchor" ac:schema-version="1" ac:macro-id="d427ddfd-74b6-47bb-960b-72d9d41a4783"><ac:parameter ac:name="">_Hlt64776435</ac:parameter></ac:structured-macro>1] or have learned otherwise about the concepts of container/component and XML binding classes to be used for ALMA software. You should also be familiar with the ALMA build environment (see [8]), even though a few things are explained redundantly in this tutorial.
While describing the steps involved in developing two sample components, I will try to provide information beyond the scope of the demo components in order to help using the framework for concrete ALMA subsystem development. However, this is not a concept or design document for the respective parts of ACS. It should help you to get started nonetheless.
The Java container/component model is fully integrated in ACS. It is meant to be used by ALMA subsystems or the parts of them that don't have real-time requirements and don't directly control hardware devices.

Abbreviations

This document no longer maintains a separate section for abbreviations. Please use the ALMA software glossary [13].

References

1. ALMA Software Architecture, Section 5 (Technical Architecture) http://almaedm.tuc.nrao.edu/forums/alma/dispatch.cgi/Architecture/docProfile/100018/d20030224132141/No/ALMASoftwareArchitecture_1.0.1.pdf
2. ACS Architecture http://www.eso.org/projects/alma/develop/acs/OnlineDocs/ACSArchitectureNL.pdf
3. ACS FAQ http://almasw.hq.eso.org/almasw/bin/view/ACS/AcsFAQ
4. Management and Access Control Interface Specification http://www.eso.org/projects/alma/develop/acs/OnlineDocs/Management_and_Access_Control_Interface_Specification.pdf
5. ACS Command Center User Guide http://www.eso.org/~almamgr/AlmaAcs/OnlineDocs/ACSCommandCenter/Acs_Command_Center_-_User_Guide.html
6. ACS Error System http://www.eso.org/~almamgr/AlmaAcs/OnlineDocs/ACS_Error_System.pdf
7. CDB Tutorial http://www.eso.org/~almamgr/AlmaAcs/OnlineDocs/CDB.pdf
8. ALMA Software Development Tools and Integration Procedures http://www.eso.org/~almamgr/AlmaAcs/OnlineDocs/IntGuidelines.pdf
9. OMG IDL to Java Language Mapping http://cgi.omg.org/cgi-bin/doc?formal/02-08-05
10. Eclipse download www.eclipse.org
11. Eclipse background information and configuration for ALMA http://almasw.hq.eso.org/almasw/bin/view/ACS/FAQJCompEclipse http://www.eso.org/~hsommer/eclipse20020923.htm
12. Castor XML Java binding framework http://castor.codehaus.org
13. ALMA software glossary http://almaedm.tuc.nrao.edu/forums/alma/dispatch.cgi/Glossary

What you need

Readers should feel very much encouraged to follow at their computers the steps described in the chapters below, switching between this tutorial and the real software.

Getting Eclipse IDE

The Java parts of the ACS framework were developed using the Eclipse IDE. Eclipse is not one of the "official" ALMA standards, but a majority of ALMA developers finds it so helpful that I like to recommend getting it. You can download Eclipse for free from [10]. The latest milestone build is usually fine, but special plugins may require to use a released version.
We have started a description on how to configure Eclipse to work well together with the ALMA build system [11]. It's expected to grow, feedback is welcome. As background information, notes from a presentation of Eclipse given at ESO are also available on that page.

Getting the source code

The ACS release (currently ACS 4.1.1) contains source code inside the delivered jar files, both for the implementation of the container, compiled IDL files etc, as well as for the examples used in this tutorial.
Automatically generated documentation and the source code for the examples can also be found online at
http://www.eso.org/projects/alma/develop/acs/OnlineDocs/jcontexmpl/doc/html/index.html.
A live web-based CVS view for all relevant ACS modules is at http://websqa.hq.eso.org/bin/viewcvs.cgi/ACS/LGPL/CommonSoftware/.
The modules that play a major role in the Java container/component part of ACS are listed below in compile order, together with the jar files they produce.

Here's an overview of the directories and files in the module jcontexmpl:

Compiling and running the examples

To compile and run the software, you need a current installation of ACS. The basic concepts for Java components have not changed since ACS 3.0 though.

Make

The /src and /test directories each contain a Makefile. The command
make clean all
will compile IDL and Java code and pack the results into jar files.
make install
will copy IDL, schema, and jar files to the respective sub-directories of your INTROOT directory so that they are available for other modules.
To learn about using the make system, refer to "man acsMakefile" and "man javaMakefile".

Run

To run the container, you must first start the ACS services & manager. Either use the graphical ACS Command Center (see [5]), or the command
acsStart
Make sure your ACS_CDB variable points to the CDB installation that you want to use. You find a CDB suitable for the examples under jcontexmpl/test in CVS. You could either use that CDB directly, or merge the entries from Components.xml into your $ACS_CDB/CDB/MACI/Components/Components.xml.
To run the container on the same machine where the Manager runs, use the command
acsStartContainer –java <containername>
For cases where the manager runs on a different machine, please refer to [3] ("FAQGeneralCompContainerOptions").
To terminate a Java container, you can use the command line
acsStopContainer <containername>
or the brute-force approach with Ctrl-C on the container console; in this case the Manager will attempt to reload components in that container next time the container runs.
The rest of ACS you terminate with
acsStop (or killACS if all else fails).

Using an IDE (Debugging!)

The recommended method is Java remote debugging, which is described in the ACS FAQs [3] under "How do I debug my components?".

Windows development with limitations

Windows aficionados can run the Java container with its components (or just a client application that accesses components) on a Windows machine that has a network connection to another machine where the rest of ACS is running. Different subversions of JDK 1.4 have worked fine on Windows.
The build process (make) is not available under Windows. Assuming you have ACS installed on a Linux machine, you should keep your source code there, and mount the directories on Windows, e.g. using Samba The ACS FAQ will describe the setup in more detail.. The initial compilation must be done on Linux to compile IDL etc. Subsequent plain Java compilations can then be done from Windows.
There is an issue with CR/LF line termination: if you get ASCII sources from CVS on Windows, they come with Windows line breaks; the build process runs on Linux though, and a few tools will fail without telling you why. The Makefile itself and the IDL files are affected. In case of doubt, run dos2unix on them, e.g.
~/CVSPRJ/ACS/jcontexmpl/src 1001 > dos2unix Makefile

Logging

By default, log messages are sent to the local console and to the central ACS logger. There they simply get absorbed in the void if you don't register for them. For example,
acsStartLoggingClient | tee mylog.xml
will send all logs messages to the file mylog.xml and also to the console where you typed the command.
To adjust the log levels that get through, you may provide your own Java logging properties file. It must be compliant to the JDK 1.4 logging spec. Refer to the FAQ for the details. As a template for the properties file, you could use almalogging.properties from acsjlog/src.
There is also a graphical application "LoggingClient" that you can start with the command
jlog

Designing the Components

During the design of your ALMA subsystem, you should partition your software into one or preferably several components The "subsystem master component" concept may be included in this tutorial in the future. A component will be the smallest chunk of software that can be deployed separately, e.g. in its own process or even on its own machine. Guidelines are that a component should be small enough to be functionally cohesive (having exactly one functional interface with related methods), but large enough to keep the number of components sufficiently small. Typically, a component will be made up of several Java classes, and a subsystem might consist of a handful of components.
There can be components that will be used by other subsystems, while other components are only used internally by the subsystem. In either case, the functional interface must be specified as CORBA IDL.
The example components that we'll look at in the tutorial are not jewels of OO design, but they are meant to illustrate the steps involved to get to an implementation. The detailed motivation for all methods used in the interfaces is described in the next section about IDL.
We will work with

• a simple Java component "HelloDemo" that implements the notorious sayHello() method, both plain and with primitive dummy parameters
• a fancier "XmlComponent" that demonstrates the handling of XML entity objects with the transparent use of Java binding classes.

The components and their containers can be pictured as follows, with the "antennas" sticking out on top being the functional interfaces.


The two Java components, HelloDemo and XmlComponent, can either run collocated inside one Java container as shown, or run in separate Java containers. The Java container is drawn as a closed box to indicate that it works as a "tight container" (cf. [1]), intercepting all functional calls to any of its components, in addition to starting/stopping the components and providing explicit services to them.
The Java components can talk with, say, a C++ component "otherComp", which must run inside a C++ container ("other Container"). That container is drawn open to indicate that it is a "porous" kind of container which only takes care of starting/stopping the components, but does not intercept functional calls on the running components.
The ACS containers use CORBA and the ACS services, the ACS Manager, and the Configuration Database. The Manager itself also uses the CDB.

Creating the HelloDemo Component

IDL

A component's functional interface must be specified as an interface in CORBA's Interface Definition Language (IDL). An IDL file may contain more than one interface. The Java container framework does not require further restrictions Currently there is a problem with IDL attributes which will be fixed later. on the usage of the more exotic IDL constructs beyond what ACS already mandates for the definition of C++ components.
Using the ALMA directory structure, you should put IDL files in the <xxxx>/idl directory of your module. Our HelloDemo component is defined in jcontexmpl/idl/HelloDemo.idl.
Let's look at the listing of HelloDemo.idl with line-by-line explanations.
01 #ifndef HELLODEMO_IDL
02 #define HELLODEMO_IDL
03 #include <acscomponent.idl>
04 #pragma prefix "alma"
05
06 module demo
07 {
08 // a very simple component
09 interface HelloDemo : ACS::ACSComponent
10 {
11 string sayHello();
12
13 string sayHelloWithParameters(in string inString,
inout double inoutDouble, out long outInt);
14 };
15 };
16 #endif

After the IDL file HelloDemo.idl has been written, a couple of Java classes must be generated from it.
The ALMA Makefile will take care of this, given the line (see jcontexmpl/src/Makefile)
IDL_FILES = HelloDemo
The generated Java classes are then automatically compiled and put into /lib/HelloDemo.jar. They belong to the package alma.demo and can be categorized as

Warning: don't choose the same name for IDL_FILES as for (one of the values of) JARFILES in your Makefile! Otherwise the jar files produced from the IDL and from your module's code have the same name and one gets overwritten by the other.

Component Implementation

The implementation of a Java component is a Java class that must implement

• the functional interface (that corresponds to the IDL definition), and the
• alma.acs.component.ComponentLifecycle interface that the container uses to start and stop the component and to provide a callback handle.

The implementation class may inherit from any base class This is possible because for Java components the framework uses the CORBA tie delegation model; C++ components can use multiple inheritance and extend the CORBA skeleton directly, thus saving one runtime delegation step.; no such base class is required by the framework though, which saves the single inheritance option offered by Java.
For components that don't need inheritance for other purposes, there is a generic base class (alma.acs.component .ComponentImplBase) that provides standard implementations of the required methods from ComponentLifecycle and ACSComponent, just to keep the component code simpler.
In real life we would usually first create the component implementation class with just dummy implementations for all mandatory methods, e.g. using code generation features of an IDE like Eclipse, and then move on to the next steps described in sections 6 and below. This document will ignore the iterative process and look at the final implementations right away.
The functional interface for the HelloDemo component is HelloDemoOperations, a Java interface generated by the CORBA IDL compiler.
By convention, we call the implementation class "HelloDemoImpl" and create it in the package "alma.demo.HelloDemoImpl". It can be found under jcontexmpl/src in CVS.
01 /* legal info cut out
19  */ 20 package alma.demo.HelloDemoImpl; 21 import java.util.logging.Logger; 22 import org.omg.CORBA.DoubleHolder; 23 import org.omg.CORBA.IntHolder; 24 import alma.ACS.ComponentStates; 25 import alma.acs.component.ComponentLifecycle; 26 import alma.acs.container.ContainerServices; 27 import alma.demo.HelloDemoOperations; 28  29 /** Javadoc cut out 37  */ 38 public class HelloDemoImpl implements ComponentLifecycle, HelloDemoOperations 39 { 40   private ContainerServices m_containerServices; 41   private Logger m_logger; 42  43   ///////////////////////////////////////////////////////////// 44   // Implementation of ComponentLifecycle 45   ///////////////////////////////////////////////////////////// 46    47   public void initialize(ContainerServices containerServices) { 48     m_containerServices = containerServices; 49     m_logger = m_containerServices.getLogger(); 50     m_logger.info("initialize() called..."); 51   } 52   public void execute() { 53     m_logger.info("execute() called..."); 54   } 55   public void cleanUp() { 56     m_logger.info("cleanUp() called..., nothing to clean up."); 57   } 58   public void aboutToAbort() { 59     cleanUp(); 60     m_logger.info("managed to abort..."); 61   } 62    63   ///////////////////////////////////////////////////////////// 64   // Implementation of ACSComponent 65   ///////////////////////////////////////////////////////////// 66    67   public ComponentStates componentState() { 68     return m_containerServices.getComponentStateManager().getCurrentState(); 69   } 70   public String name() { 71     return m_containerServices.getComponentInstanceName(); 72   } 73    74   ///////////////////////////////////////////////////////////// 75   // Implementation of HelloDemoOperations 76   ///////////////////////////////////////////////////////////// 77    78   public String sayHello() { 79     m_logger.info("sayHello called..."); 80     return "hello"; 81   } 82    83   public String sayHelloWithParameters(String inString, 84       DoubleHolder inoutDouble, IntHolder outInt) { 85     m_logger.info("sayHello called with arguments inString="  inString 86          "; inoutDouble="  inoutDouble.value 87          ". Will return 'hello'..."); 88     outInt.value = (int) Math.round(Math.E * 10000000); 89     return "hello"; 90   } 91 }

Note that the implementation of the HelloDemo component is done with just one Java class. A real component would rather have one main implementation class that implements the component interfaces and uses other classes to perform the functional tasks.

Creating the XmlComponent Component

Unlike the previous HelloDemo, the component XmlComponent uses entity objects that are transported over the network as serialized XML. We will focus on this feature and not repeat things which have already been demonstrated before.

XML entity classes

Overview

The term "entity" refers to non-primitive, non-binary data with identity such as scheduling blocks, system users, correlator configurations etc., c.f. [1]. These data types are defined in XML schemas. Their instances are XML "documents" that get passed around by value and can be stored in the ALMA Archive.
From the XML schemas, we produce Java classes at build-time, based on the Castor framework [12]. These binding classes represent the hierarchical data structure in memory. They have type-safe methods to navigate the tree and to access data items. The binding classes can be automatically instantiated from XML documents that correspond to the same schema, and can serialize their data into stringified XML.
The idea of "transparent XML entities" is to have the entity objects transported by CORBA as language-neutral XML strings. However, the Java component implementations (both client and server involved in the remote call) don't have to worry about the serialization and parsing of the XML. The main advantage of this is that the framework ensures type safety, from the IDL/schema definitions, all the way down to the Java implementation classes of a component; it's not possible to be surprised at runtime that the received XML differs in type or version from what the component expected. To achieve this, the implementation classes use modified component interfaces, in which Java binding classes are substituted for the structs with serialized XML. An example with detailed explanation will be given in 5.3.
A Java component that acts either as a client or as a server with respect to some other component, is completely independent in its decision whether to parse XML entity objects "by hand" or to enjoy transparent support for binding classes. The other component may be written in Java, C+, or whatever other language, and it may or may not use binding classes If this other component is written in Java, the developer has a real choice on this; for C+ at least at the moment there is no support for XML binding classes, so the C++ XML parser (expat) that comes with ACS should be used..
For example, a Java client that exchanges XML entity objects with a C++ server can work with Java binding classes, whereas the C++ server parses the XML using a SAX parser.

Designing entity schemas

We define complex data types in XML schema and use these types in CORBA IDL similar to how CORBA structs would be used.
To keep this tutorial focused on component development, we only touch on the schema development issue. Rather than showing how to develop a new schema, we use the existing schemas from the module acstestentities.
For XML schemas describing ALMA entities, there are the following conventions:

• One schema per entity. This means that the entity "SchedBlock" must be defined in a different XML schema than the entity "ObsProject". "Different schema" really means "different schema namespace"; on the file level, one schema can be composed of various files connected through <xsd:include>, as long as these files belong to the same namespace. The reason for using included files would be to make large schemas more readable for the human eye.
• XML namespaces: the typical convention would be to use a namespace that looks like an internet URL (e.g. targetNamespace="http://www.alma.org/xmlschemas/obsprep"). This does not work for ALMA though, since "alma.org" is not ours, and "alma.int" conflicts with the integer type in Java. Thus in ALMA, the namespace should be "Alma/<subsystem>/<schemaName>" (e.g. "Alma/ObsPrep/SchedBlock"). Our test schemas use the namespace "AlmaTest/schemaName" instead.
• XML schemas consist of "elements" and "types". Names of schema types must end with a "T", like in <xsd:complexType name="ObsUnitT">. This avoids problems with generating binding classes (e.g. alma.mypackage.ObsUnitT), and makes it easier to find a name for a wrapper class that adds functionality to such a binding class (e.g. alma.mywrappers.ObsUnit).
• Top-level entities are defined as the root elements in a schema file, like ObsProject or SchedBlock. To allow the system to store administrational data like ID, version etc., the root element must have a child element of type EntityT (defined in the ACS module "define"/idl/CommonEntity.xsd, with the xml namespace "Alma/CommonEntity"). For example, in the schema file ObsProject.xsd, the schema element ObsProject has a child of type ObsProjectEntityT, which inherits from EntityT.Perhaps it would have been more intuitive to use an inheritance convention instead of composition (SchedBlock could inherit from EntityT), but since XML schema only allows single inheritance, we don't want to use it up for the sake of the framework. In the file SchedBlock.xsd we see that in fact our schema element "SchedBlock" inherits from ObsUnitT, which would not have been possible otherwise.
• From one entity object (that is, an XML document) you can reference another entity object through the ID. In the schema, this must be declared uniformly using (a subtype of) EntityRefT, which declared in the schema file CommonEntity.xsd. For example, a SchedBlock references the ObsProject to which it belongs. The schema element SchedBlock has a child element ObsProjectRef whose type inherits from EntityRefT. Therefore, an XML document for a SchedBlock entity can reference another XML document that is an ObsProject.

Compiling entity schemas

Schema files must be put into the /idl directory of your module, or into the ICD/<yourSubsystem>/ws/idl directory if Like IDL files are meant to be used by other subsystems. Please check with ALMA software engineering.
You must add information to your module's Makefile so that the XML schemas can be compiled into Java binding classes. Let's look at how acstestentities/src/Makefile has it:
XSDBIND = acsTestEntities
tells the build process to look for a configuration file ../idl/acsTestEntities.xml which must provide information about the schema files to be compiled (see below). The resulting Java classes will then be packed into ../lib/acsTestEntities.jar.
Schema files can include or import other schema files. In our case, CommonEntity.xsd from the module ACS/define, systementities.jar, is imported. In our Makefile, the line
XSDBIND_INCLUDE = systementities
is required so that the build process can set the include path for the schema compiler.
Here's a reduced listing of the configuration file /idl/acsTestEntities.xml
<?xml version="1.0" encoding="UTF-8" ?>
<EntitybuilderSettings>
  <EntitySchema schemaName="TestObsProject.xsd" xmlNamespace="AlmaTest/ObsProject" />
  <EntitySchema schemaName="TestObsProposal.xsd" xmlNamespace="AlmaTest/ObsProposal" />
  <EntitySchema schemaName="TestSchedBlock.xsd" xmlNamespace="AlmaTest/SchedBlock" />
  <XmlNamespace2JPackage xmlNamespace="AlmaTest/ObsProject" jPackage="alma.xmljbind.test.obsproject" />
  <XmlNamespace2JPackage xmlNamespace="AlmaTest/ObsProposal" jPackage="alma.xmljbind.test.obsproposal" />
  <XmlNamespace2JPackage xmlNamespace="AlmaTest/SchedBlock" jPackage="alma.xmljbind.test.schedblock" />
</EntitybuilderSettings>
We see that schema files are listed together with their xml namespaces (<EntitySchema>). Then the namespaces are mapped to Java packages (<XmlNamespace2JPackage>). Files and packages are separated here because several schema files can use the same xml namespace, but the Java package of the resulting classes must depend on the namespace, not the schema file.
Note that the compilation of xml schemas is specified differently in the Makefile, compared with the compilation of IDL files. IDL files are listed individually and are compiled into one jar file each, whereas schema files are only referenced indirectly through their XML configuration file, and are compiled into only one jar file per module.
The diagram below illustrates the relationships among the xml schema files, IDL files, and Makefiles from our module "acsjexmpl" and the modules "define" and "acstestentities" from where resources are used by the example module.

IDL

Using XML schema types in IDL – general idea

The diagram below shows how to use the XML schema definition of a SchedBlock in the IDL definition of a component interface.

XmlComponent.idl

Here's a thinned-out listing. Since lines are missing, we use letter tags instead of line numbers.
A #include <xmlentity.idl>
#include <acscomponent.idl>
B #pragma prefix "alma"
C module demo
{
D typedef xmlentity::XmlEntityStruct ObsProposal;
typedef xmlentity::XmlEntityStruct SchedBlock;
typedef sequence <SchedBlock> SchedBlockSeq;
E exception XmlComponentException {};
F struct ObsProjectTree
{
ObsProposal prop;
SchedBlockSeq schedBlocks;
};
G interface XmlComponent : ACS::ACSComponent
{
H long dumbMethod(in string somevalue);
I ObsProposal createObsProposal();
J SchedBlockSeq getAllSchedBlocks();
K void xmlInOutMethod(in ObsProposal opsPropIn,
out SchedBlock schedBlockOut);
L ObsProjectTree getEntireTreeInAStruct();
M void exceptionMethod() raises (XmlComponentException);
};
};

Compiling IDL

We have to add the new IDL file to jcontexmpl/src/Makefile:
IDL_FILES = HelloDemo XmlComponent
In addition to running this file through the standard CORBA IDL compiler, it is also fed into the "ACS IDL compiler". This tool gets started by the build process, so you never have to see it; the interested reader can find it in the CVS module ACS/…/XmlIdl. The ACS IDL compiler creates additional Java classes which the CORBA IDL compiler would not create. They are used for working with Java XML binding classes instead of plain XML strings, see 5.1.1.
In the Makefile, the line
XML_IDL = "ObsProposal=alma.xmljbind.test.obsproposal.ObsProposal; \
SchedBlock=alma.xmljbind.test.schedblock.SchedBlock"
provides the mapping from IDL typedefs (see lines 6-8) to Java binding classes (conceptually: to the schema that defines the entities).
The Java files that are produced from XmlComponent.idl are

The classes shown in normal print are mandated by CORBA standards and generated by the CORBA IDL compiler, while the italicized classes are required by the ACS framework and are generated by the ACS IDL compiler.

Component implementation

In section 5.2, we saw the IDL file with the typedefs for the entity classes, and their use in the methods of the XmlComponent interface.
The following two functional interfaces have been generated for XmlComponent. The component implementation must implement one of them:

• XmlComponentOperations uses serialized XML; if the component implemented this interface, it would have to parse and serialize the xml entity objects "manually".
• XmlComponentJ uses Java binding classes; the container will offer transparent parsing and serialization of XML.

We will choose the convenience and type-safety offered when implementing XmlComponentJ. The interface generated by the ACS IDL compiler is listed below (Javadoc lines omitted).
<span style="color: #808080">01</span> <span style="color: #7f0055"><strong>package </strong></span>alma.demo; <span style="color: #808080">02</span>  <span style="color: #808080">03</span> <span style="color: #3f5fbf">/**</span> <span style="color: #808080">04</span> <span style="color: #ffffff"> </span><span style="color: #3f5fbf"><strong> XML binding class aware ACS component interface XmlComponentJ </strong>/</span> <span style="color: #808080">05</span> <span style="color: #7f0055"><strong>public interface </strong></span>XmlComponentJ <span style="color: #7f0055"><strong>extends </strong></span>alma.ACS.ACSComponentOperations <span style="color: #808080">06</span> { <span style="color: #808080">10</span> <span style="color: #ffffff">    </span><span style="color: #7f0055"><strong>public int </strong></span>dumbMethod(String somevalue); <span style="color: #808080">11</span>  <span style="color: #808080">15</span> <span style="color: #ffffff">    </span><span style="color: #7f0055"><strong>public </strong></span>alma.xmljbind.test.obsproposal.ObsProposal createObsProposal(); <span style="color: #808080">16</span>  <span style="color: #808080">25</span> <span style="color: #ffffff">    </span><span style="color: #7f0055"><strong>public </strong></span>alma.xmljbind.test.schedblock.SchedBlock[] getAllSchedBlocks(); <span style="color: #808080">26</span>  <span style="color: #808080">30</span> <span style="color: #ffffff">    </span><span style="color: #7f0055"><strong>public void </strong></span>addNewSchedBlocks(
alma.xmljbind.test.schedblock.SchedBlock[] newSchedBlocks); <span style="color: #808080">31</span>  <span style="color: #808080">35</span> <span style="color: #ffffff">    </span><span style="color: #7f0055"><strong>public void </strong></span>xmlInOutMethod(
alma.xmljbind.test.obsproposal.ObsProposal opsPropIn, 
alma.demo.SchedBlockHolder schedBlockOut); <span style="color: #808080">36</span>  <span style="color: #808080">40</span> <span style="color: #ffffff">    </span><span style="color: #7f0055"><strong>public </strong></span>alma.demo.ObsProjectTreeJ getEntireTreeInAStruct(); <span style="color: #808080">41</span>  <span style="color: #808080">50</span> <span style="color: #ffffff">    </span><span style="color: #7f0055"><strong>public void </strong></span>exceptionMethod() <span style="color: #808080">51</span> <span style="color: #ffffff">        </span><span style="color: #7f0055"><strong>throws </strong></span>alma.demo.XmlComponentException; <span style="color: #808080">53</span> }
Comparing this with the IDL definition, we see that binding classes like alma.xmljbind.test.schedblock.SchedBlock are used whenever the IDL contained a typedef'd entity struct. In addition to this direct substitution, the ACS IDL compiler created the class ObsProjectTreeJ which contains binding classes, thus substituting the IDL struct ObsProjectTree as the return type of the method getEntireTreeInAStruct();
Let's look at the implementation of the method createObsProposal().
<span style="color: #808080">121</span> <span style="color: #ffffff">  </span><span style="color: #7f0055"><strong>public </strong></span>ObsProposal createObsProposal() <span style="color: #808080">122</span> <span style="color: #ffffff">  </span>{ <span style="color: #808080">123</span> <span style="color: #ffffff">    </span>ObsProposal obsProp = <span style="color: #7f0055"><strong>new </strong></span>ObsProposal(); <span style="color: #808080">124</span> <span style="color: #ffffff">    </span> <span style="color: #808080">125</span> <span style="color: #ffffff">    </span><span style="color: #7f0055"><strong>try</strong></span> <span style="color: #808080">126</span> <span style="color: #ffffff">    </span>{ <span style="color: #808080">127</span> <span style="color: #ffffff">      </span>ObsProposalEntityT entity = <span style="color: #7f0055"><strong>new </strong></span>ObsProposalEntityT(); <span style="color: #808080">128</span> <span style="color: #ffffff">      </span>m_containerServices.assignUniqueEntityId(entity); <span style="color: #808080">129</span> <span style="color: #ffffff">      </span>obsProp.setObsProposalEntity(entity); <span style="color: #808080">130</span> <span style="color: #ffffff">      </span> <span style="color: #808080">131</span> <span style="color: #ffffff">      </span>obsProp.setPerformanceGoals(
<span style="color: #2a00ff">"peak performance enduring a 24-7-365 schedule."</span>); <span style="color: #808080">132</span> <span style="color: #ffffff">    </span>} <span style="color: #808080">133</span> <span style="color: #ffffff">    </span><span style="color: #7f0055"><strong>catch </strong></span>(ContainerException e) <span style="color: #808080">134</span> <span style="color: #ffffff">    </span>{ <span style="color: #808080">135</span> <span style="color: #ffffff">      </span>m_logger.log(Level.SEVERE, <span style="color: #2a00ff">"failed to create ObsProposal. "</span>, e); <span style="color: #808080">136</span> <span style="color: #ffffff">    </span>} <span style="color: #808080">137</span> <span style="color: #ffffff">    </span> <span style="color: #808080">138</span> <span style="color: #ffffff">    </span><span style="color: #7f0055"><strong>return </strong></span>obsProp; <span style="color: #808080">139</span> <span style="color: #ffffff">  </span>}
We see that the Java class ObsProposal has type-safe methods like "setPerformanceGoals" or "setObsProposalEntity".
The latter takes an object of type ObsProposalEntityT, also generated by the binding framework. It is used to store administrational information about the ObsProposal object, most important the object ID.
For a new entity object, a valid and unique object ID can be obtained conveniently through a call to ContainerServices#assignUniqueEntityId, for which the container collaborates with the archive. If the archive is not present, it defaults to using random numbers which should be almost always unique (2^64).
Our method implementation simply returns the top-level Java object for the ObsProposal. The container framework will then automatically serialize it to XML, embed the string in the XmlEntity CORBA struct, and send it to the client using CORBA. If the client is another Java component, its container will automatically create an ObsProposal class and fill it with the data from the serialized XML.
To keep the size of this tutorial small, the implementations of the other methods are not listed here. They are meant to serve as more detailed examples, for which the source code of the module jcontexmpl should be retrieved anyway.
Alternatively, the code listing can be found online at the ACS documentation site:
http://www.eso.org/projects/alma/develop/acs/OnlineDocs/jcontexmpl/doc/html/XmlComponentImpl_8java-source.html
To see how the code would look like if the component would implement XmlComponentOperations, take a look at the inner class XmlComponentHelper::IFTranslator.

Component Helper Classes

For each component class, a corresponding helper Naming convention: For the component of an interface "xxx", the helper file is named as "xxxComponentHelper". This should not be so easily confused with the IDL-generated "xxxHelper". class is needed. In most cases this helper class will be used only by the framework, which means that the component developer will not have to look at it much.
The framework uses the helper class to

• instantiate the component implementation class
• get information about the component's interface(s)
• get the CORBA POA Tie skeleton class for the component

A template for the helper class gets generated automatically by the build system if the Makefile contains the line
COMPONENT_HELPERS=on
The template has a file ending .java.tpl to ensure that no edited .java helper class gets overwritten. It is meant as a convenience for the component developer who will normally just have to remove the .tpl ending and then treat that Java file like his/her own, which requires checking it into CVS.
For our HelloDemo component, the helper class does not need to be changed (some Javadoc lines stripped from the listing):
23 package alma.demo.HelloDemoImpl; 24  25 import java.util.logging.Logger; 26  27 import alma.acs.component.ComponentLifecycle; 28 import alma.acs.container.ComponentHelper; 29 import alma.demo.HelloDemoOperations; 30 import alma.demo.HelloDemoPOATie; 31 import alma.demo.HelloDemoImpl.HelloDemoImpl; 32  33 /** 38  * To create an entry for your component in the Configuration Database,  39  * copy the line below into a new entry in the file $ACS_CDB/MACI/Components/Components.xml  40  * and modify the instance name of the component and the container:  42  * Name="HELLODEMO1" Code="alma.demo.HelloDemoImpl.HelloDemoComponentHelper" Type="IDL:alma/demo/HelloDemo:1.0" Container="frodoContainer" 45  */ 46 public class HelloDemoComponentHelper extends ComponentHelper 47 { 52   public HelloDemoComponentHelper(Logger containerLogger) 53   { 54     super(containerLogger); 55   } 56  60   protected ComponentLifecycle _createComponentImpl() 61   { 62     return new HelloDemoImpl(); 63   } 64  68   protected Class _getPOATieClass() 69   { 70     return HelloDemoPOATie.class; 71   } 72  76   protected Class _getOperationsInterface() 77   { 78     return HelloDemoOperations.class; 79   } 80  81 }
Only in special situations, when a Java component chooses to sometimes use Java binding classes, but other times send or receive serialized XML instead, then the helper class must be modified. This goes beyond the scope of this tutorial and will be described in a more specialized document.
An example for this can be found in alma.demo.XmlComponentImpl.XmlComponentComponentHelper from jcontexmpl/src/.

Configuration Database

The ACS configuration database contains information about which components are deployed on the different machines. It assists the ACS Manager to locate components at runtime. All the runtime action is hidden from the programmer by the container.
There are two different types of components:

• static components whose instances are fixed at deployment time. These typically represent (abstracted) hardware devices, or service components for which we choose a fixed number of instances. One component can be deployed many times under different names, like "Pipeline1", "Pipeline2".

• dynamic components whose type (and optionally container location) is fixed at deployment time, whereas the number and names of instances is determined only at runtime. For more details on this, refer to [3], topic "FAQGeneralCompDynamic".

Let's make HelloDemo a static component. We create a new line in the file CDB/MACI/Components/ Components.xml with

• The instance name ("Name"), which has the format of an ACS CURL, and is used by a client to get access to the component. We call it HELLODEMO1.
• The component helper class ("Code", see section 6)
• The CORBA interface repository ID of the component ("Type" – remember that to CORBA a component is just a servant).
• The name of the Java container that will be asked by the ACS Manager at runtime to instantiate our components – called "frodoContainer" in the examples.

Note that the generated component helper class contains these values in a comment (code listing above, line 42). This facilitates adding the CDB entry using copy and paste.
The CDB file Components.xml then looks similar to
<?xml version="1.0" encoding="utf-8"?>
<Components xmlns="urn:schemas-cosylab-com:Components:1.0"
xmlns:cdb="urn:schemas-cosylab-com:CDB:1.0"
xmlns:baci="urn:schemas-cosylab-com:BACI:1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<_ Name="TEST_PS_1" Code="acsexmplPowerSupplyImpl"
Type="IDL:alma/PS/PowerSupply:1.0" Container="bilboContainer"/>
<_ Name="HELLODEMO1" Code="alma.demo.HelloDemoImpl.HelloDemoHelper"
Type="IDL:alma/demo/HelloDemo:1.0" Container="frodoContainer" />
<_ Name="XMLCOMP1" Code="alma.demo.XmlComponentImpl.XmlComponentHelper"
Type="IDL:alma/demo/XmlComponent:1.0" Container="frodoContainer" />
<_ Name="LAMP1" Code="acsexmplLamp" Type="IDL:ALMA/PS/Lamp:1.0" Container="bilboContainer"/>
<_ Name="OPERATIONAL_ARCHIVE" Code="alma.archive.components.OperationalHelper"
Type="IDL:alma/xmlstore/Operational:1.0" Container="frodoContainer" />
</Components>
ACS ships with a default CDB that contains the entries for the demo components.
You'll have to add entries for your own components, or create a new CDB structure and reset the ACS_CDB environment variable.

Clients

A component can have different kinds of clients which we'll discuss separately:

Generic Client: ObjectExplorer

We can use the ACS tool ObjectExplorer as a generic client for all components. Run it with
objexp
and you should find your Java components (e.g. XmlComponent) and their instances (e.g. XMLCOMP1) listed on the dialog, together with C++ components (e.g. Lamp).
At first, you see only a visualization of the information in the CDB, as opposed to actually loaded components. When you click on a component instance, the Manager will tell the Container to activate the component with the given instance name.
The screenshot shows the output after XMLCOMP1 has been loaded and the method getBestSchedBlock has been called (with View → Expand result data checked in ObjectExplorer.)

Client Component

We've seen the example of a Java component accessing a C++ Component in 4.2, and a Java component accessing another Java component without transparent XML binding support referenced in 5.1.
To use support for xml binding classes on the client side of a call, we first obtain the other component (here: XMLCOMP1)
XmlComponent xmlComp = alma.demo.XmlComponentHelper.narrow(
getComponent("XMLCOMP1"));
and then ask the container to wrap it with the more convenient interface that uses XML binding classes, provided in the ContainerServices interface
XmlComponentJ xmlCompJ =
(XmlComponentJ) m_containerServices.createXmlBindingWrapper(
XmlComponentJ.class,
xmlComp,
XmlComponentOperations.class);
Now we can keep working with xmlCompJ, and the framework will delegate all calls to xmlComp, translating between XML binding classes and serialized XML presentation in between.

JUnit Test Client

To facilitate the writing of JUnit test clients, ACS (module jcont) offers the class
alma.acs.component.client.ComponentClientTestCase
which is a subclass of JUnit's TestCase that does the talking with ACS Manager. It provides most of the functionality that ContainerServices provides for components.
A JUnit test that gets a reference to the XmlComponent component and runs some tests on it is
jcontexmpl/src/alma.demo.client.XmlComponentClient
020 package alma.demo.client; 022 import alma.acs.component.client.ComponentClientTestCase; 023 import alma.demo.SchedBlockHolder; 024 import alma.demo.XmlComponent; 025 import alma.demo.XmlComponentException; 026 import alma.demo.XmlComponentJ; 027 import alma.demo.XmlComponentOperations; 028 import alma.entities.commonentity.EntityT; 029 import alma.xmljbind.test.obsproposal.ObsProposal; 030 import alma.xmljbind.test.schedblock.SchedBlock; 031  039 public class XmlComponentClient extends ComponentClientTestCase 040 { 042   private XmlComponentJ m_xmlCompJ; 043  049   public XmlComponentClient() throws Exception { 050     super("XmlComponentClient"); 051   } 052  053   protected void setUp() throws Exception { 054     super.setUp(); 055  056     org.omg.CORBA.Object compObj = getContainerServices().getComponent( 057         "XMLCOMP1"); 058     assertNotNull(compObj); 059     XmlComponent xmlComp = alma.demo.XmlComponentHelper.narrow(compObj); 060  061     m_xmlCompJ = (XmlComponentJ) getContainerServices() 062         .getTransparentXmlComponent(XmlComponentJ.class, xmlComp, 063             XmlComponentOperations.class); 064  065     assertNotNull(m_xmlCompJ); 066   } 067  071   public void testSayHelloUsingHelloDemoComponent() { 072     String reply = m_xmlCompJ.sayHello(); 073     assertNotNull(reply); 074     System.out.println("received reply "  reply); 075     assertEquals("reply must be 'hello'", "hello", reply); 076   } 077  081   public void testCreateObsProposal() { 082     ObsProposal obsProp = m_xmlCompJ.createObsProposal(); 083     assertNotNull(obsProp); 084  085     EntityT ent = obsProp.getObsProposalEntity(); 086     assertNotNull(ent); 087  088     String id = ent.getEntityId(); 089     assertNotNull(id); 090  091     System.out.println("received ObsProposal with id "  id); 092   } 093  094   public void testXmlInOutMethod() { 095     ObsProposal obsProp = m_xmlCompJ.createObsProposal(); 096     assertNotNull(obsProp); 097     SchedBlockHolder sbh = new SchedBlockHolder(); 098  099     m_xmlCompJ.xmlInOutMethod(obsProp, sbh); 100  101     SchedBlock schedBlock = sbh.value; 102     assertNotNull(schedBlock); 103  104     EntityT ent = schedBlock.getSchedBlockEntity(); 105     assertNotNull(ent); 106     String id = ent.getEntityId(); 107     assertNotNull(id); 108  109     System.out.println("received out-param SchedBlock with id " + id); 110   } 111  117   public void testException() throws Exception { 118     boolean gotException = false; 119  120     try { 121       m_xmlCompJ.exceptionMethod(); 122     } 123     catch (XmlComponentException e) { 124       gotException = true; 125       System.out.println("received XmlComponentException as intended."); 126     } 127  128     assertTrue("must receive XmlComponentException", gotException); 129   } 130 }
The constructor must call the constructor of the base class (c.f. line 50) with a name to be used for this client (here: "XmlComponentClient"). If you override the setup() method, it's necessary there to call super.setUp() first (see line 54).
JUnit will call all methods that start with "test" in their name, such as testException().
In the Eclipse Java Perspective, you can run such a class with JUnit. Open the class in the editor, then choose
Menu Run → Run As → JUnit Test. It will display the results.