elemenope userguide v1.2

8/14/2019 elemenope userguide v1.2

http://slidepdf.com/reader/full/elemenope-userguide-v12 1/71

elemenope TM User Guide

john joseph roets

May 29, 2007Version 1.2

For Release With elemenope Version 5.1

c MMVI-MMVII john joseph roets and createTank



1

Copyright (c) 2006-2007 john joseph roets and createTank. Permission is granted tocopy, distribute and/or modify this document under the terms of the GNU Free Documen-tation License, Version 1.2 or any later version published by the Free Software Foundation;with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of thelicense is included in the section entitled ”GNU Free Documentation License”.



Contents

1 Introduction 71.1 Intent of This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.2 What Is elemenope? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.3 History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

1.4 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81.5 Goals of elemenope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2 Architectural Features 102.1 Abstraction of Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . 102.2 Functional Abstraction (Business Logic Abstraction) . . . . . . . . . . . . . 102.3 Transport Abstraction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122.4 Payload Abstraction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142.5 Abstraction of Synchrony . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182.6 Fault Tolerant Messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

3 Interfaces 20

3.1 Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203.2 Connectivity Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

3.2.1 Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213.2.2 Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213.2.3 Dispatcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

4 Business Logic (Operation) Implementation 224.1 Execute Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224.2 Methods Inherited From ElemenopeComponent . . . . . . . . . . . . . . . . 23

4.2.1 SetCongurationAttributes Method . . . . . . . . . . . . . . . . . . 234.2.2 SetComponents Method . . . . . . . . . . . . . . . . . . . . . . . . . 244.2.3 ReleaseComponents Method . . . . . . . . . . . . . . . . . . . . . . . 25

2



CONTENTS 3

5 Conguration 265.1 elemenope Standard Conguration . . . . . . . . . . . . . . . . . . . . . . . 26

5.1.1 elemenope Standard Conguration System Contract . . . . . . . . . 265.1.2 elemenope Conguration File Structure . . . . . . . . . . . . . . . . 295.1.3 Main Conguration . . . . . . . . . . . . . . . . . . . . . . . . . . . 295.1.4 User Conguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305.1.5 Operation Conguration . . . . . . . . . . . . . . . . . . . . . . . . . 315.1.6 Service Conguration . . . . . . . . . . . . . . . . . . . . . . . . . . 325.1.7 Standardized Ingest & Default Service/Operation Conguration . . 335.1.8 Dispatcher Failover [DFo] Conguration . . . . . . . . . . . . . . . . 33

5.2 elemenope Spring Framework Conguration . . . . . . . . . . . . . . . . . . 355.3 elemenope Application Server Integration . . . . . . . . . . . . . . . . . . . 36

A Cookbook 38A.1 Service Conguration Examples . . . . . . . . . . . . . . . . . . . . . . . . . 38

A.1.1 Direct Call Service Transport Protocol . . . . . . . . . . . . . . . . . 38A.1.2 Java Message Service [JMS] . . . . . . . . . . . . . . . . . . . . . . . 39A.1.3 XML-RPC Web Service . . . . . . . . . . . . . . . . . . . . . . . . . 40A.1.4 SOAP Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45A.1.5 Native IBM MQSeries/WebsphereMQ . . . . . . . . . . . . . . . . . 47A.1.6 Mainframe Connectivity Classes . . . . . . . . . . . . . . . . . . . . 49

A.2 Usage of BPM Operation Implementations . . . . . . . . . . . . . . . . . . . 49A.2.1 ElemenopeAsyncBpmChainOperation . . . . . . . . . . . . . . . . . 49A.2.2 ElemenopeProcessListOperation . . . . . . . . . . . . . . . . . . . . 51A.2.3 ElemenopeProcessChainOperation . . . . . . . . . . . . . . . . . . . 52A.2.4 ElemenopeBpmListOperation . . . . . . . . . . . . . . . . . . . . . . 53A.2.5 ElemenopeBpmChainOperation . . . . . . . . . . . . . . . . . . . . . 54A.2.6 ElemenopeBpmPayload.java . . . . . . . . . . . . . . . . . . . . . . . 55

A.3 Generic Ingest Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55A.4 elemenope Standard Conguration Maintenance Loop . . . . . . . . . . . . 56A.5 Spring Framework Conguration and Integration Within elemenope . . . . 57

B FAQ 59

C Resources 63C.1 Internet Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63C.2 Email Discussion Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63C.3 Online FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

C.4 Spring Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63C.5 createTank Support for elemenope . . . . . . . . . . . . . . . . . . . . . . . 63



CONTENTS 4

D GNU Free Documentation License 64



List of Figures

2.1 Functional Abstraction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.2 Functional Abstraction in elemenope . . . . . . . . . . . . . . . . . . . . . . 112.3 Transport Abstraction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.4 Payload Abstraction Doppelganger Extension Generation Phase . . . . . . . 15

2.5 Payload Abstraction Doppelganger Extension Usage Phase . . . . . . . . . 152.6 Payload Abstraction with RosettaType . . . . . . . . . . . . . . . . . . . . . 172.7 Synchronous to Asynchronous Dispatcher Failover . . . . . . . . . . . . . . 19

5.1 elemenope Standard Conguration Flowchart . . . . . . . . . . . . . . . . . 285.2 Simple Dispatcher Failover . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345.3 Dispatcher Failover Chain . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

5



Listings

4.1 Operation execute() example . . . . . . . . . . . . . . . . . . . . . . . . . . 234.2 Operation setCongurationAttributes() example . . . . . . . . . . . . . . . 244.3 Operation setComponents() example . . . . . . . . . . . . . . . . . . . . . . 254.4 Operation releaseComponents() example . . . . . . . . . . . . . . . . . . . . 255.1 < initializationGroup > conguration example . . . . . . . . . . . . . . . . . 29

5.2 < main > conguration example . . . . . . . . . . . . . . . . . . . . . . . . . 305.3 < user> conguration example . . . . . . . . . . . . . . . . . . . . . . . . . 305.4 < operations > conguration example . . . . . . . . . . . . . . . . . . . . . . 315.5 < services> conguration example . . . . . . . . . . . . . . . . . . . . . . . . 325.6 dispatcher failover conguration example . . . . . . . . . . . . . . . . . . . . 335.7 ElemenopeStartupServlet web.xml conguration example . . . . . . . . . . 37A.1 Direct Call Service Transport Protocol Conguration Example . . . . . . . 38A.2 JMS Service Transport Protocol Conguration Example . . . . . . . . . . . 39A.3 XML-RPC Server Service Transport Protocol Conguration Example . . . 41A.4 XML-RPC Client Service Transport Protocol Conguration Example . . . . 42A.5 Enterprise XML-RPC Conguration Example . . . . . . . . . . . . . . . . . 43

A.6 web.xml XML-RPC Servlet Conguration Example . . . . . . . . . . . . . . 45A.7 SOAP Service Transport Protocol Conguration Example . . . . . . . . . . 46A.8 MQSeries/WebsphereMQ Service Transport Protocol Conguration Example 48A.9 ElemenopeAsyncBpmChainOperation Conguration Example . . . . . . . . 50A.10 ElemenopeProcessListOperation Conguration Example . . . . . . . . . . . 51A.11 ElemenopeProcessChainOperation Conguration Example . . . . . . . . . . 52A.12 ElemenopeBpmListOperation Conguration Example . . . . . . . . . . . . 53A.13 ElemenopeBpmChainOperation Conguration Example . . . . . . . . . . . 54A.14 IngestFileSystemOperation Conguration Example . . . . . . . . . . . . . . 55A.15 Example Implementation of Maintain Method . . . . . . . . . . . . . . . . . 57A.16 Very Simple Conguration Bean Example . . . . . . . . . . . . . . . . . . . 57A.17 Very Simple Spring Conguration Example . . . . . . . . . . . . . . . . . . 58

6



Chapter 1

Introduction

1.1 Intent of This Guide

This guide is intended to be read by software architects and developers looking to use theelemenope framework for efficient application development.

1.2 What Is elemenope?

elemenope is a Service Oriented Architecture [SOA], Enterprise Application Integration[EAI], and general messaging framework.

elemenope may also be considered to be an application toolkit, as it contains nearlyeverything one needs to develop a complete application.

elemenope is a Framework Framework. It is the basis for more than one major Frame-work which has a requirement for a SOA. elemenope makes it easy for a Framework to addSOA capabilities to its feature set.

“elemenope” is pronounced L-M-N-O-P or more specically \ ”el-em-en-O-’pE \ . Anaudio sample of the proper pronunciation can be found here:http://elemenope.org/audio/elemenope.wav

elemenope implements several advanced software architecture concepts.

1.3 History

elemenope has been in development since 1999. It and some of its precursors are currentlyin production use within several organizations large and small.

elemenope started as a manner in which to simplify the process of integrating legacyenterprise systems with new development.

elemenope was at its inception SOA, long before Service Oriented Architecture wascoined or marketed as a buzzword.

7



CHAPTER 1. INTRODUCTION 8

elemenope has served over the years as a proving grounds for several advanced softwarearchitecture concepts. These concepts were put to tangible use within elemenope and haveproven successful in multiple implementations in a variety of industries.

elemenope was released as Free and Open Source Software [FOSS] in 2003. Originallylicensed under the GNU Public License [GPL], the Apache License Version 2.0 was addedas an additional licensing option in 2006.

1.4 Features

• Architectural Features

– Abstraction of transport/protocol connectivity — Abstraction of connectivity is-sues promotes ability to integrate new software with legacy applications throughsimplication of connections (see §2.1).

– Functional logic (business logic) abstraction — ability to separate business logicimplementation code from the service protocol implementation which is callingit (see §2.2).

– Transport/protocol abstraction — ability to change service transport protocolin conguration le with no change to business logic implementation code (see§2.3).

– Payload abstraction — The ability to send a payload (the object sent to theOperation) without regard to what protocol might be in use (see §2.4).

– Synchrony abstraction — the proposed ability to generically call a Service/Oper-ation without regard to whether the target service is congured as a Synchronousor Asynchronous protocol (see §2.5).

– Fault Tolerant Messaging — the ability to transparently failover a call or requestfrom one service transport protocol to another upon failure with no changes tothe functional code or business logic implementation (see §2.6).

• SOA built into core

• Simplication of Application Architecture

• Powerful separation of Service (transport) from Operation (functional) implementa-tions

• Massive decoupling of an enterprise’s components through standardized communica-

tions interfaces.• Platform for simplied software development on top of an extremely advanced archi-

tectural environment.



CHAPTER 1. INTRODUCTION 9

• Fully developed application toolkit

• Simplied creation of large scale multi-platform application for messaging or trans-action processing.

• Simplication of the architecture of large enterprise systems through standardizationof functional components and message pathways.

• Simplied tracing of problems and collection of metrics at multiple levels, as everyunit of application functionality implements the same interface, and all requests followa similar path.

• Architected at a much higher level than most other SOA implementations to be trans-port and protocol agnostic, and to concentrate on providing multiple architecturalabstractions.

• EAI components for integration of mainframe application

• Current implementations of service transport protocol sets:

– Java Message Service [JMS]– SOAP Web Services– XML-RPC Web Services– Direct Call– Native IBM MQSeries (WebSphereMQ)– Built-in mainframe connectivity classes for use when connecting to a mainframe

running IBM MQSeries with the IMS Adapter or IMS Bridge

1.5 Goals of elemenope

• Abstraction of connectivity within an enterprise application

• Ease incorporation of detailed knowledge from subject matter experts

• Implementation of multiple transports

• Transport agnostic business logic implementation

• Ability to congure and recongure service transport protocol and services

• Simplication of Enterprise Application Architecture• Powerful and extensible SOA through separation of Service from Operation



Chapter 2

Architectural Features

2.1 Abstraction of Connectivity

Connectivity abstraction is the ability to connect to various components or services throughany of the implemented protocols with changes to the standard elemenope congurationle — i.e. without code changes or additions. Connectivity abstraction is achieved throughthe service transport protocol implementations.

This is one of the simplest architectural features offered by the elemenope Framework.It was also the rst feature developed into elemenope. This feature offers a great savingsof time for new projects, as connectivity to various systems is built in, allowing developersto spend valuable time on implementation of business logic, the real goal of their project.

2.2 Functional Abstraction (Business Logic Abstraction)

Functional Abstraction or Business Logic Abstraction is the ability to separate businesslogic implementation code from the service protocol implementation which is calling it (Fig.2.1). Business logic abstraction is achieved in elemenope through the implementation of the Operation interface (Fig. 2.2).

This architectural feature allows the user to implement the business logic in a mannergeneric to its execution. This separation also tends to simplify the code, as no connectivitydetails or other extraneous code need enter into the picture. It is often the case thatSubject Matter Experts [SME] with little coding experience may implement the sometimescomplex business logic, as the Operation interface execute() method is extremely simple,and can tend to provide for procedural programming within, for those not accustomedor comfortable with Object Oriented [OO] Programming. We have taken advantage of

this aspect of the Operation interface on many projects where the team may not havebeen made up of highly skilled Java or OO savvy developers. An application’s Operationimplementations may be as simple or as complex as required.

10



CHAPTER 2. ARCHITECTURAL FEATURES 11

Figure 2.1: Functional Abstraction

Figure 2.2: Functional Abstraction in elemenope




Another aspect of the Operation interface is its lending to a customized business logichierarchy. That is, when a project has many separate business logic Operation implemen-tations which often are required to conduct similar processing, logging, or etc., a team maycreate an OO hierarchy which handles said processing in an abstract parent Operationimplementation.

2.3 Transport Abstraction

Transport Abstraction is the ability to change service transport protocol implementationsin the elemenope conguration le with no change to business logic implementation code.Transport abstraction is achieved through the use of standardized connectivity interfaceswithin elemenope for all service transport protocol implementations (see Fig. 2.3).

This architectural feature offers great benet to users of elemenope, as an organizationmay lower risks involved with regard to technologies and service protocols deployed. Theorganization may determine at a later date that a different protocol is required. Thismay then be changed at runtime via a conguration le. The originally deployed servicetransport protocol might also be augmented with another service implementation in adiffering protocol, congured to offer the same business logic implementations or a subsetthereof.

This architectural feature also allows alternative environments (e.g. development ortesting) to simplify deployment conguration without change to the business logic imple-mentation code.




Figure 2.3: Transport Abstraction




2.4 Payload Abstraction

Payload abstraction is the ability to send a payload (the request object sent to a Service)without regard to what protocol might be congured.

This architectural feature is made necessary due to the novel characteristic of the ele-menope Framework that it is capable of switching protocols at runtime through the use of a conguration le 1 . The fact that different protocols allow different data types led to aproblem in the past of payload denition in real systems. That is, a system would eitherneed to determine at design time all possible service protocol implementations that mightbe used by their application for all time, or a payload would need to be designed with“least common denominator” data types. For example, the Direct Call Service Protocolimplementation allows any Java type to be sent. The JMS Service Protocol implementa-tion only allows a subset of these types. The XML-RPC Service Protocol implementationallows an even more limited subset of Java types. In order to switch from one protocol toanother, the payload design must implement only the simplest types which all protocols

will accept without error, or use Payload Abstraction.

Payload abstraction is achieved within elemenope in one of the following manners:

Doppelganger extension Doppelganger is an extension to the elemenope Frameworkwhich requires an XML schema denition for the payload. This schema is used todynamically generate Java classes (see Fig. 2.4) which may be used to marshalldata to XML and back. The payload is the generated XML. In this manner, allprotocols (at least all protocols implemented at this time) may pass the marshalledXML without error. The Services and their congured Operation implementationsonly ever see the objects of the classes generated by Doppelganger (see Fig. 2.5).Doppelganger uses the Castor Project Open Source data binding framework. TheCastor Project may be found at: http://www.castor.org/

1 This capability is termed “Transport Abstraction” — see §2.3




Figure 2.4: Payload Abstraction Doppelganger Extension Generation Phase

Figure 2.5: Payload Abstraction Doppelganger Extension Usage Phase




RosettaType RosettaType is a project which denes a generic data structure and severalprotocol and language specic RosettaEngines. These RosettaEngines translate aninstantiated object of any given data type to the RosettaType structure and back tothe original object, i.e. from POJO 2 to RosettaType and back to POJO (see Fig. 2.6).RosettaType provides the most efficient mechanism for payload abstraction, as theRosettaEngine implementation in use for a particular protocol will only translate or“roll out” datatypes which are not supported in that protocol. All other datatypeswithin the generic payload will be left as-is for simple passage. The RosettaTypeimplementation is not complete. Multiple protocols have been implemented, and arecurrently being reviewed. When integrated into the elemenope Framework, each ser-vice protocol implementation will gain a class extended from the base implementationto handle the RosettaType functionality. This extension of the base implementationclass will allow a user to utilize the simpler form of the service protocol implemen-tation, and only utilize the RosettaType form if needed. RosettaType is maintainedby createTank. The RosettaType project is Free and Open Source [FOSS].

When completely implemented, the RosettaType will likely be the preferred methodfor payload abstraction, as it offers the most natural form, not requiring any design fore-thought.

2 POJO — Plain Ol’ Java Object




Figure 2.6: Payload Abstraction with RosettaType




Figure 2.7: Synchronous to Asynchronous Dispatcher Failover



Chapter 3

Interfaces

3.1 Operation

The Operation is the single, simple Interface within elemenope for functional abstraction.Implementation of this Interface may be as simple or complex as required.

• Purely procedural in the case of simple functionality requirements, or limited SubjectMatter Expert [SME] coding capabilities.

• Object Oriented [OO] Programming and the full power of Enterprise Java wherecomplex modeling is needed.

The Operation Interface consists of a single method 1 execute() which takes an plainObject argument, and returns a plain Object. All processing which this Operation imple-ments should take place within (or be called from within) this method.

3.2 Connectivity Interfaces

The implementation of the following elemenope standard Interfaces make up a servicetransport protocol implementation. Service transport protocol implementations may ormay not implement these Interfaces in the same manner. For instance, some implemen-tations may share the same Connector implementation for both client and server, whilstothers may implement two separate Connector classes. Full details of Service TransportProtocol implementation is beyond the scope of the elemenope User Guide. The informa-tion provided within this section is a high level description of Interfaces appropriate to theneeds of the elemenope user. More information concerning implementation of a service

1 An Operation implementation will actually implement more than this method, as Operation itself extends the Interface ElemenopeComponent, which requires implementation of three conguration specicmethods. For more information, see Chapter 4: Operation Implementation .

20



CHAPTER 3. INTERFACES 21

transport protocol may be found within the elemenope source code (RTFC!) , or within theupcoming elemenope Developer Guide (when it becomes available :)).

3.2.1 Connector

The Connector usually holds the connectivity information or attributes and the connectionitself (if there is one) for the service transport protocol. The Connector sometimes providesa manner in which said connectivity information or attributes may be provided to theBroker and/or Dispatcher.

3.2.2 Broker

The Broker implements the receipt functionality for the service transport protocol. Thisconsists of receiving a message generically and routing it to the proper Operation imple-mentation (Operations are congured in the elemenope conguration le to be available toa given service)

3.2.3 Dispatcher

The Dispatcher implements the transmission functionality for the service transport proto-col. It is through this interface that a user may generically call other services as a client.The user’s Operation implementation will call the service’s operation by name and theactual Dispatcher implementation to be called is congured and changeable at runtime.



Chapter 4

Business Logic (Operation)Implementation

This chapter will illustrate the manner in which an Operation may be implemented.

4.1 Execute Method

The execute() method within all Operation implementations must be coded to be reen-trant 1 , as the user must assume that the elemenope Framework may execute the codewithin this method with multiple threads.

The primary method which the non-abstract Operation implementation must imple-ment is the execute() method (listing 4.1). This method is called once per service oper-ation request.

1 reentrant - can be safely called recursively or from multiple tasks [denition taken from http://en.wikipedia.org/wiki/Reentrant ].

22



CHAPTER 4. BUSINESS LOGIC (OPERATION) IMPLEMENTATION 23

public Ob jec t execu t e ( Ob j ec t ob j ec t ){

/ t h i s i s a s am pl e e x e c u t e m et ho d i m p l em e n ta t io n i f t h i s we re a r e a l i mp le me nt at io n , s t an da r d t y pec h ec k in g s h ou l d b e p er fo rm ed b e f o r e c a s t i n g t h e p as s ed O b je ct t o t h e u se r d e f in e d t y pe .

/ UserDef inedPayload payload = ( UserDef inedPayload) obj ec t ;S t r i ng pay l oadAt t r i bu t e = payl oad . ge t At tr i bu t eX ( ) ;

// d o s o me th in g w it h t h i s a t t r i b u t eS t r i ng r e s u l t = ” Th is i s t he p as se d a t t r i b u t e : ” + p a yl o ad A tt r ib u te ;

return r e s u l t ;}

Listing 4.1: Operation execute() example

In the example (listing 4.1), the payload is passed, cast to the proper payload type,processed, and the processed result is returned.

The payload class is dened by the user, and may be any Java Object. A commonpractice is to use a Map implementation class (e.g. HashMap or Hashtable) as the payloadclass, and refer to it throughout the application code as a Map interface. This allows oneto easily add attributes to the payload as the application grows.

4.2 Methods Inherited From ElemenopeComponent

Three methods inherited from the ElemenopeComponent Interface must also be imple-mented: setConfigurationAttributes() , setComponents() , and releaseComponents() .Each of these methods is called only once at the initialization (or shutdown) of the ele-menope Framework 2 .

4.2.1 SetCongurationAttributes Method

The setConfigurationAttributes() method provides a user the ability to pass propertiesor settings to the Operation implementation from the conguration le (listing 4.2). Itaccepts a Map argument, which contains any values encoded in the XML attributes of

2

Each method is called only once per instantiated Operation class. That is, if a user congures a partic-ular Operation implementation class in two Operation Groups within the conguration le, the elemenopeFramework will instantiate two separate instances of the class, and thus call each of the said methods onceper class.




the operation node corresponding to this Operation instantiation within the elemenopeconguration le. Anything may be done with these values.

public void se t Co nf i gu r a t i o nAt t r i bu t e s ( Map a t t s ) throws ElemenopeException{

/ e x t r a ct any s p e c i a l a t t r i b u t e s r e qu i re d f rom t hec o n f i g u ra t i o n f i l e O pe ra ti on a t t r i b u t e s

/ Str in g databaseName = at ts . get (”databaseName” ) ;

/ a l t e r n a t i v e l y , one m ig ht u se t he e n t i r eMap a s a p r o p e r t i e s t a b l e . . .

/ th i s . props = new Pr ope r t i e s ( a t t s ) ;

} Listing 4.2: Operation setCongurationAttributes() example

4.2.2 SetComponents Method

The setComponents() method provides the user access to all other components instanti-ated within the elemenope Framework (listing 4.3). It accepts an ElemenopeComponentsobject as an argument. The ElemenopeComponents class provides multiple conveniencemethods for accessing all Elemenope standard components and user components withinthe system. This method is called after all elemenope Framework initialization is com-

plete, yet before connections and Services are “started”. Typically, an Operation willextract needed components and store them within a class level variable, for use within theexecute() method.




public void setComponents ( ElemenopeComponents components ){

/ some i m p l em ent a t i ons may s t o r e t he f u l l com ponent sr e f e re n c e f o r f u t u r e u se . . .

/ th i s . components = components ;

/ a l t e r n a t i v e l y , one m ig ht o nl y e x t r a c t t h a t w hic h i s n ee ded ( t h i s i s b e t t e r p r a c t i c e t ha n t h a t a bo ve ) . . .

/ th i s . d i spa tcherA = components . ge tDispa tch er (” d i spa tcherA” ) ;

}

Listing 4.3: Operation setComponents() example

4.2.3 ReleaseComponents Method

The releaseComponents() method provides the user the ability to clean up or releasesystem resources that might have been consumed in the setup of this Operation (listing4.4). It accepts a void argument. This method is called from within the elemenopestandard initialization shutdown process.

public void releaseComponents ( ){

/ c l o s e a d a t ab a s e c o n ne c t io n . . .

/ conn . c lo se ( ) ;conn = nul l ;

/ c l os e an open f i l e . . .

/ f i l e . c l os e ( ) ;f i l e = nul l ;

}

Listing 4.4: Operation releaseComponents() example



Chapter 5

Conguration

This chapter provides the user with descriptions and requirements for conguration of theelemenope Framework.

5.1 elemenope Standard Conguration

The elemenope standard conguration consists of the conguration of all elemenope basecomponents from the elemenope.xml conguration le. This conguration has been thebasis of the initialization of the framework since its beginning. Only recently have theuser components been open to simplied conguration utilizing the Spring Framework (see§5.2).

5.1.1 elemenope Standard Conguration System Contract

elemenope has a standard conguration system contract, which denes the order and man-ner in which components are initialized. The order of initialization procedures follows assuch...

1. Initialize General Settings — initialize items within the < main > node of the cong-uration le.

• The maintenance interval is set — This value determines how many millisecondswill pass before each iteration of the elemenope maintenance cycle.

• The default Service and Operation names are set (if any) — If set, this defaultService will be called requesting this default Operation once per each itera-tion of the elemenope maintenance cycle. This allows an application to call an

Operation implementation periodically (e.g. maintenance, ingestion, or otherprocessing code).

2. Initialize Operations — all congured Operations will be instantiated and initialized.

26



CHAPTER 5. CONFIGURATION 27

3. Initialize Services — for each congured Service, do the following...

(a) Initialize Service Connectors(b) Initialize Service Broker (if any)(c) Initialize Service Dispatcher (if any)

4. Initialize User Components

5. Initialize Spring Framework (if congured)

6. Propagate Components — All objects within the framework (including the user de-ned components) will be checked recursively (all Collections and Maps will be re-cursed). All objects which implement the ElemenopeComponent Interface will havetheir setComponents(ElemenopeComponents) method called with the fully popu-lated ElemenopeComponents object.

7. Start Services




Figure 5.1: elemenope Standard Conguration Flowchart




5.1.2 elemenope Conguration File Structure

The elemenope standard conguration le is elemenope.xml. Within this le, the root nodeis < elemenope > . There may be one or more < initializationGroup > nodes dened therein.

Each < initializationGroup > node will contain the following sections...• main

• user

• operations

• services

< elemenope >

< i n i t i a l i z a t i on Gr o up name=”exampl eConfi g” >

< main. . ./ >

< use r. . ./ >

< o p e r a t i o n s >

. . .< / o p e r a t i o n s >

< s e r v i c e s>

. . .< / s e r v i c e s >

< / i n i t i a l i z a t i o n G r o u p >

< /e lemenope >

Listing 5.1: < initializationGroup > conguration example

5.1.3 Main Conguration

The “main” section denes three attributes...

1. The maintenance interval is set — This value determines how many milliseconds willpass before each iteration of the elemenope maintenance cycle.




2. The default Service name — The name of the Service called at each iteration of themaintenance cycle (see §5.1.7).

3. The default Operation name — The name of the Operation called at each iteration

of the maintenance cycle (see §5.1.7).

< mainmaintenanceInterva l=”30000”de f au l t Se r v i ce= ”exam pl eSe r v i ce”defaul tOpera t ion=”exampleOpera t ion”

/ >

Listing 5.2: < main > conguration example

5.1.4 User CongurationThe “user” section denes one attribute, the Spring Framework conguration le name.For more details on the use of this conguration, please see §5.2.

< use rsp r i ngConf i gu r a t i onF i l e= ”conf / sp r i ng . xm l ”

/ >

Listing 5.3: < user> conguration example




5.1.5 Operation Conguration

The conguration of one or more Operations is fairly straightforward. Within the < operations >

section, multiple < operationGroup > sections may be dened, each containing one or more< operation > congurations. Each Broker conguration will be assigned an operationGroupattribute, which will contain the congured Operations which that Broker may call uponrequest.


< operat ionGr oup name=”example” >

< ope r a t i onname=”operation1”c l a s s=”your . package .name . OperationExample1”

/ >

< ope r a t i onname=”operation2”

c l a s s=”your . package .name . OperationExample2”k ey=” o p t i o n a l p r o pe r t y v a l ue f o r y ou r o p e r a t i on ”/ >

< /operat ionGroup >

< / o p e r a t i o n s >

Listing 5.4: < operations > conguration example

All XML attributes contained within the operation node(s) are passed completely in-tact as a Map to the respective Operation’s setComponents() method. In the above ex-ample (listing 5.4), the second Operation conguration “operation2” contains an undenedXML attribute “key”. This attribute (along with all others dened [including “name” and

“class”]) is passed as a key/value pair within a Map to the Operation’s setComponents()method at initialization. In this manner, a user may pass conguration parameters to theirOperation implementations.




5.1.6 Service Conguration

The conguration of a service has been greatly simplied as of elemenope version 5.0.Within the < initializationGroup > section, a < services> section is dened which may con-

tain one or more < service> sections (see listing 5.5). Each < service> section must containa < connector > section and either one or both of a < broker > and < dispatcher > section.The elemenope standard conguration requires a minimum set of attributes for each Inter-face within a service transport protocol. Each service transport protocol implementationwill dene its own attributes in addition to the minimum. For service transport protocolspecic conguration examples, please see §A.1.

< s e r v i c e s>

< s e r v i c ename=”tes tService”

>

< connec torc l as s=”com. c rea te tank . e lemenope . t r a nsp or t s . Di rec tCal lC onnector ”

/ >

< brokerc l as s=”com. c rea te tank . e lemenope . t r an spo r t s . Di rec t Cal l Broker ”operationGroup=”example”

/ >

< d i s p a t c h e rc l as s=”com. c rea te tank . e lemenope . t r ans por t s . Di r ec tCa l lD isp a tche r”

/ >

< / s e r v i c e >

< / s e r v i c e s >

Listing 5.5: < services> conguration example

The elemenope standard conguration minimum denition of each section is as follows...

Connector

Must contain a class attribute. This is the class which will be instantiated by the frame-work. This class must implement the Connector interface.

Broker

Must contain a class attribute and an operationGroup attribute. The class is that whichwill be instantiated by the framework. This class must implement the Broker interface.

The operationGroup attribute determines which congured operationGroup will beassigned to this Broker. Only those Operations dened within that named operationGroupwill be accessible to this Broker for client requests.




Dispatcher

Must contain a class attribute. This is the class which will be instantiated by the frame-work. This class must implement the Dispatcher interface.

5.1.7 Standardized Ingest & Default Service/Operation Conguration

A common need for applications is to ingest data from the lesystem or other resource. Onemay utilize the < main > section attributes to do this by calling a user dened Operationon every iteration of the elemenope maintenance cycle.

There are plans to implement multiple ingest operations to generically ingest lesystemand possibly POP/IMAP resources.

5.1.8 Dispatcher Failover [DFo] Conguration

The conguration of Dispatcher Failover [DFo] consists of the addition of the “failoverList”

attribute to the < dispatcher > node within the < service> conguration section. This at-tribute should be set to a comma-delimited list of the Dispatchers to which the messageshould be passed upon failure. The Dispatchers should be referred to by service name. Ser-vice name(s) placed into the DFo list must be dened within the same initializationGroupto be recognized (see listing 5.6).

< d i s p a t c h e rc l as s=”com. c rea te t ank . e lemenope . t r ans por t s . Di re c tCal lDi spa t cher ”failoverList=”DFO1,DFO2”

/ >

Listing 5.6: dispatcher failover conguration example




Figure 5.2: Simple Dispatcher Failover

Failover may be congured in a much more complex manner with Dispatcher Failoverchaining. This is nothing more than the failover of a failover in a chain as long as a usermay need (Fig. 5.3).




Figure 5.3: Dispatcher Failover Chain

5.2 elemenope Spring Framework Conguration

The congured Spring Framework conguration le (see User Conguration §5.1.4) is readas a FileSystemXmlApplicationContext. 1 The user must create one or more bean classes

which will contain any or all conguration properties for the user’s application. The SpringFramework will then populate this class or classes with the values from within the SpringFramework conguration le. The elemenope Framework then stores the instantiated andpopulated bean or beans within the ElemenopeComponents object for the elemenope ini-tialization group. The user may then access any of these beans from within the frameworkvia two static methods of the Elemenope class. The rst, getSpringBeanFactory() ac-cepts the ElemenopeComponents object within which the Spring Framework was invoked,and returns the Spring Framework BeanFactory object, with which a user may do anySpring Framework specic activities wished. The second, getSpringBean() , accepts againthe ElemenopeComponents object within which the Spring Framework was invoked, andthe bean name or id from within the Spring conguration le, and returns the user’s actual

bean as instantiated and populated.1 FileSystemXmlApplicationContext is a Spring Framework specic class. For more information about

the Spring Framework, please visit http://www.springframework.org/ .




A further point in the conguration of elemenope utilizing the Spring Framework, isthe ability of the user to access any or all components (elemenope and user components)congured in the application from within the Spring Framework user bean by simply imple-menting the ElemenopeComponent Interface in said bean. That is, if the Spring Frameworkuser bean implements the ElemenopeComponent Interface, its setComponents() methodwill be called and passed the fully populated ElemenopeComponents at framework initial-ization.

Please note that Spring Framework conguration is only available for elemenope version5.0 and above.

5.3 elemenope Application Server Integration

elemenope may be integrated into a web application or Enterprise Java application via theElemenopeStartupServlet , a Java Servlet implementation which congures one or moreelemenope initialization groups congured within a standard elemenope.xml congurationle. The conguration of this Servlet resides within a web application’s web.xml le.

ElemenopeStartupServlet Attributes

congClass The implementation of the ElemenopeConfiguration Interfaceto use. This will likely always be ElemenopeStandardConfiguration ora subclass.

congFile The le to use for a conguration le.initializationGroupX The name of each individual initializationGroup to

congure (named within the congured congFile). Multiple initializa-tionGroups may be listed, each with a new < init-param > , and each witha differing < param-name > . However, the < param-name > for each must begin with the string “initializationGroup”. Please see the example inlisting 5.7.

log4jCongFile The Log4j conguration le.log4jWatchInterval The cyclical interval after which Log4j will check the

Log4j conguration le for changes, incorporating any changes which havebeen made.




< s e r v l e t >

< s e r v l e t − name> elemenope < / s e r v l e t − name>

< s e r v l e t − c l a s s>

com. cre ate tan k . e lemenope . ElemenopeS tar tup Servle t< / s e r v l e t − c l a s s>

< i n i t − param >

< param − name> c o n f i g C l a s s< /param − name>

< param − va l ue> com. cr eat eta nk . e lemenope . ElemenopeStandardConf igurat ion < /para< / i n i t − param >


< param − name> c o n f i g F i l e< /param − name>< param − va l ue> /opt /elemenope/conf/elemenope .xml < /param − value >

< / i n i t − param >


< param − name> i n i t i a l i z a t i o n G r o u p 1 < /param −name>

< param − va l ue> initGroupExample1 < /param − value >



< param − name> i n i t i a l i z a t i o n G r o u p 2 < /param −name>

< param − va l ue> initGroupExample2 < /param − value >



< param − name> l o g 4 j C o n f i g F i l e < /param −name>

< param − va l ue> /opt /e lemenope/conf /e lemenope . log4 j . p r ope r t i es < /param − va l ue>< / i n i t − param >


< param − name> l og4 j Wat ch I n t e r va l < /param −name>

< param − va l ue> 15000< /param − va l ue>


< load − on− s t a r t up > 1< / load − on− s t a r t up >

< / s e r v l e t >

Listing 5.7: ElemenopeStartupServlet web.xml conguration example



Appendix A

Cookbook

This chapter provides one with multiple examples of conguration and implementationexamples.

A.1 Service Conguration Examples

A.1.1 Direct Call Service Transport Protocol

The Direct Call Service Transport Protocol implementation is the simplest implementationin elemenope. Conguration consists of the minimum required attributes for each of theConnector, Broker, and Dispatcher. In the example (listing A.1), all “class” attributesmust be as shown, while the service “name” may be any string, and operationGroup maybe the name of any operationGroup congured within the same initializationGroup.

< s e r v i c enam e= ”d i r ec t Ca l l Se r v i ce”>

< connec torc l as s=”com. c rea te tank . e lemenope . t r a nsp or t s . Di rec tCal lC onnector ”

/ >

< brokerc l as s=”com. c rea te tank . e lemenope . t r an spo r t s . Di rec t Cal l Broker ”operat ionGroup=”exampleOperat ions”

/ >

< d i s p a t c h e rc l as s=”com. c rea te tank . e lemenope . t r ans por t s . Di r ec tCa l lD isp a tche r”

/ >

< / s e r v i c e >

Listing A.1: Direct Call Service Transport Protocol Conguration Example

38



APPENDIX A. COOKBOOK 39

A.1.2 Java Message Service [JMS]

The JMS Service Transport Protocol implementation is one of the oldest implementationsin elemenope. Conguration consists of the minimum required attributes for each of the

Connector, Broker, and Dispatcher plus JMS specic elements. In the example below(listing A.2), all “class” attributes must be as shown, while the service “name” may be anystring, and operationGroup may be the name of any operationGroup congured within thesame initializationGroup. A description of the JMS specic attributes follows...

< s e r v i c ename=”jmsService”

>

< connec torclass=”com. createtank . elemenope . transports . JmsQueueConnector”connec t ionFacto ry=”Connect ionFactory”in i t i a lCo nte xtF ac t ory=”org . jnp . i n t e r fa ce s . NamingContextFac tory”

providerURL=”loca lhos t :1099”url Pac kag ePr ef i xes=”org . jb os s . naming”/ >

< brokerclass=”com. createtank . elemenope . transports . JmsQueueBroker”operat ionGroup=”exampleOperat ions”queueName=”queue/queueName”sessionAcknowledgementMode=”AUTO”sessionCount=”5”messageGuidedBpmEnabled=”true”

/ >

< d i s p a t c h e rcl as s=”com. cr eat eta nk . e lemenope . t r an sp or ts . JmsQueueDispatcher”queueName=”queue/queueName”

/ >

< / s e r v i c e >

Listing A.2: JMS Service Transport Protocol Conguration Example

JMS Connector Attributes

All JMS specic Connector attributes are JMS provider specic. That is, eachJMS provider or application server will require its own specic attributes forconnectivity. The example attributes (listing A.2) are for connectivity to the

JBoss application server JMS provider.connectionFactory The connection factory class used by the JMS provider

implementation.




initialContextFactory The initial context factory used for JNDI lookup bythe JMS provider implementation.

providerURL The URL for connection to the JMS server.

JMS Broker Attributes

queueName The JMS queue name upon which messages will be received forthis Service.

sessionAcknowledgementMode The JMS acknowledgement mode for thisqueue. Available values are CLIENT for manual client acknowledgement,DUPS OK for “at least once delivery”, and AUTO for automatic acknowl-edgement of messages. 1 AUTO is the default value.

sessionCount The number of JMS sessions (threads) assigned to “listen” tothis queue.

messageGuidedBpmEnabled Whether this Broker is capable of handlingBPM attributes for guiding a message through a BPM process list.

JMS Dispatcher Attributes

queueName The JMS queue name to which messages will be sent for thisService.

Please note that an actual implementation might or might not contain both a Broker andDispatcher conguration. For more generic Service conguration information, see §5.1.6.

A.1.3 XML-RPC Web ServiceXML-RPC is a clean and simple web services or remote procedure call specication (seehttp://www.xmlrpc.com/ ). elemenope utilizes the Apache XML-RPC implementation(http://ws.apache.org/xmlrpc/ ) for the XML-RPC service transport protocol imple-mentation. The XML-RPC service transport protocol implementations utilize separateConnector implementations for server and client.

elemenope has multiple sets of XML-RPC implementations.

• Simple XML-RPC implementation — Very simple conguration and implementa-tions.

• Simple elemenope specic implementation — For use in connectivity with anotherinstance of elemenope only.

1 For a formal denition of these options, see the Message Acknowledgment section of the JMS Speci-cation ( http://java.sun.com/products/jms/docs.html )




• Enterprise level XML-RPC Servlet receipt functionality implementation — for stan-dard XML-RPC connectivity within a Servlet container or application server.

• Enterprise level XML-RPC receipt functionality implementation — For standard

XML-RPC connectivity within a standalone elemenope instance (elemenope version 5.1 and later) .

The elemenope Team recommends the use of either of the enterprise level implemen-tations in a production or other critical environment for receipt functionality. The simpleimplementation clients may be safely used for transmission or Dispatcher functionality inthese environments. The simple implementations of receipt or Broker functionality areintended for use in test, development, or other non-critical uses.

Simple XML-RPC implementations

The elemenope specic implementation serializes the payload to send it to an XML-RPC

service running also on elemenope, where the payload is de-serialized before routing tothe Operation called. Both ends of this process must congure for the use of the ele-menope specic classes. The only difference in conguration between the standard andthe elemenope (serialized payload) types is the Broker and Dispatcher classes used. Forthe standard type, use XmlRpcBroker and XmlRpcDispatcher . For the elemenope specictype, use XmlRpcElemenopeBroker and XmlRpcElemenopeDispatcher . These Broker im-plementations are not intended for production use in the “real world”. For multi-threadedimplementations ready for production use, please see the section Enterprise Level XML-RPC Implementations in the following pages.

< s e r v i c ename=”xmlRpcServerService”

>

< connec torcl as s=”com. c rea tet ank . e lemenope . t r an sp or ts . XmlRpcServerConnector”a c c e p t L i s t = ” 1 9 2 . 1 6 8 . 1 . 2 ”denyLi s t = ”192 . 168 . 1 . 3”paranoid=”true”port=”9000”

/ >

< brokercl as s=”com. c rea tet ank . e lemenope . t r an sp or ts . XmlRpcBroker”operat ionGroup=”exampleOperat ions”

/ >

<

/ s e r v i c e>

Listing A.3: XML-RPC Server Service Transport Protocol Conguration Example




< s e r v i c ename=”xmlRpcClientService”

>

< connec torcl as s=”com. c rea tet ank . e lemenope . t r an sp or ts . XmlRpcClientConnector”u r l =” h t t p : // l o c a l h o s t : 9 0 0 0 ”

/ >

< d i s p a t c h e rcl as s=”com. c rea tet ank . e lemenope . t r an sp or ts . XmlRpcDispatcher”webServiceTarge t=”xmlRpcServerService”

/ >

< / s e r v i c e >

Listing A.4: XML-RPC Client Service Transport Protocol Conguration Example

XML-RPC Server Connector Attributes

acceptList A list of IP addresses from which requests are accepted by theXML-RPC server. May contain * as a wildcard character (e.g. “192.168.1.*”).

denyList A list of IP addresses from which requests are denied by the XML-RPC server. May contain * as a wildcard character (e.g. “192.168.1.*”)

paranoid Switch to turn on or off accept and deny client ltering.port Port to which the XML-RPC server will listen.

XML-RPC Client Connector Attributes

url Address to which the client will connect.

XML-RPC Broker Attributes

Minimum standard conguration for simple XML-RPC Broker.

XML-RPC Dispatcher Attributes

webServiceTarget The Service name of the target XML-RPC service (orBroker).

Enterprise Level XML-RPC implementations

For enterprise level XML-RPC Service usage, such as one needs within a production envi-ronment, elemenope provides two implementations: a Jetty HTTP Server based Connectorand Broker ( XmlRpcEnterpriseConnector and XmlRpcEnterpriseBroker ) and a Servletbased Broker ( XmlRpcServletBroker ).




Enterprise XML-RPC Implementations — Embedded Jetty HTTP Server Im-plementation

The Jetty HTTP Server based implementation ( XmlRpcEnterpriseConnector and

XmlRpcEnterpriseBroker ) is available as of elemenope version 5.1 and later. This im-plementation allows a much simpler conguration than its predecessor, the XML-RPCServlet Broker. The conguration is contained entirely within the standard elemenope.xmlconguration le. This implementation also allows simplied deployment, as the imple-mentation may run within the same JVM as non-XML-RPC services. To date, this isthe recommended enterprise XML-RPC receipt implementation. Multiple Brokers may becongured within this implementation, each handling a different XML-RPC web service.Thus, under a single URL (or context path), multiple XML-RPC web services may becongured. Each Broker congured must be congured with a different webServiceNameattribute for this to work (see the section Enterprise XML-RPC Broker Attributes belowfor details).

< s e r v i c ename=”xmlRpcEnterpriseService”

>

< connec torcl as s=”com. cr eat eta nk . e lemenope . t ra ns po rt s . XmlRpcEnterpriseConnector”h o s t = ” l o c a l h o s t ”port=”9000”minThreads=”5”maxThreads=”20”maxIdleTime=”60000”

/ >

< broker

cl as s=”com. cr eat eta nk . e lemenope . t ra ns po rt s . XmlRpcEnterpriseBroker”operat ionGroup=”exampleOperat ions”webServiceName=”xmlRpcWebService1”

/ >

< brokercl as s=”com. cr eat eta nk . e lemenope . t ra ns po rt s . XmlRpcEnterpriseBroker”operat ionGroup=”exampleOperat ions”webServiceName=”xmlRpcWebService2”

/ >

< / s e r v i c e >

Listing A.5: Enterprise XML-RPC Conguration Example




Enterprise XML-RPC Connector Attributes

host Hostname for service HTTP listener.• required: no

• default: localhostport Port for service HTTP listener.

• required: YES• default: none

minThreads Minimum number of threads for embedded Jetty HTTP server.• required: no• default: 1

maxThreads Maximum number of threads for embedded Jetty HTTP server.• required: no• default: 10

maxIdleTime Number of milliseconds for embedded Jetty HTTP server lis-tener to wait before closing and restarting listener.

• required: no• default: 60000 (60 seconds)

Enterprise XML-RPC Broker Attributes

webServiceName The name of the XML-RPC web service. If this attributeis provided, the XML-RPC service will be available at the following URL:(http://hostname:port/serviceName/webServiceName.operationName ).If this attribute is not provided, the XML-RPC service will be available at

the following URL: ( http://hostname:port/serviceName/serviceName.operationName ).

• required: no• default: serviceName

Enterprise XML-RPC — Servlet Broker Implementation

The Servlet implementation may run within a Servlet container (e.g. Jakarta Tomcat),and benet from the threading capabilities therein. This implementation is not conguredin the same manner as normal services, (i.e. within the elemenope.xml conguration le).This implementation must be used alongside the ElemenopeStartupServlet within a webapplication. The conguration of this implementation must also point to an initializationgroup which is congured by the ElemenopeStartupServlet . The conguration of thisimplementation resides within the said web application’s web.xml le. More informationon the proper conguration of the ElemenopeStartupServlet may be found within §5.3.




< s e r v l e t >

< s e r v l e t − name> xmlRpcService < / s e r v l e t −name>

< s e r v l e t − c l a s s>

com. cr eat eta nk . e lemenope . t r an sp or ts . XmlRpcServletBroker< / s e r v l e t − c l a s s>


< param − name> serviceName < /param − name>

< param − va l ue> exampleService < /param − value >



< param − name> i n i t i a l i z a t i o n G r o u p < /param −name>

< param − va l ue> e x a m p l e I n i t i a l i z a t i o n G r o u p < /param − va l ue>



< param − name> operat ionGroup < /param −name>

< param − va l ue> exampleOperat ions < /param − value >


< load − on− s t a r t up > 1< / load − on− s t a r t up >

< / s e r v l e t >

Listing A.6: web.xml XML-RPC Servlet Conguration Example

A.1.4 SOAP Web Service

SOAP is a web services protocol for exchanging XML based messages (see http://en.wikipedia.org/wiki/SOAP ). elemenope utilizes the Apache Axis implementation ( http://ws.apache.org/axis/ ) for the Soap service transport protocol implementation. Thisimplementation only supports client connectivity. Server connectivity must be implemented

separately within an Apache Axis based web application. There is an extension to el-emenope available (elemenope SOAP extension) which will automatically create SOAPservice implementation classes. This extension is not available within the elemenope-coreFOSS distribution. The use of this extension is beyond the scope of this document. Formore information, contact createTank at [email protected] .

elemenope has two sets of SOAP Dispatcher implementations:

• SoapDispatcher — Congured and called in the manner of all Dispatcher imple-mentations, with operationType and payload arguments.

• SoapMethodDispatcher — Congured with only one operation in mind. This methodstill takes the standard Dispatcher Interface arguments of operationType and pay-

load, however, only the congured operation will be called.




< s e r v i c ename=”soapCl ientService”

>

< connec torcl as s=”com. crea tet ank . e lemenope . t ran sp or ts . SoapClien tConnector ”serv iceNS=”ht tp : / / soapin te rop . org /”serv iceName=”soapService”wsdlL ocat io n=”wsdl / example . wsdl”

/ >

< d i s p a t c h e rcl as s=”com. crea tet ank . e lemenope . t ran sp or ts . SoapDispatch er”u r l =” h t t p : / / l o c a l h o s t : 9 0 0 0 ”

/ >

< / s e r v i c e >

< s e r v i c ename=”soapClientMethodService”

>

< connec torcl as s=”com. crea tet ank . e lemenope . t ran sp or ts . SoapClien tConnector ”serv iceNS=”ht tp : / / soapin te rop . org /”serv iceName=”soapService”wsdlL ocat io n=”wsdl / example . wsdl”

/ >

< d i s p a t c h e rcl as s=”com. cr eat eta nk . e lemenope . t r an sp or ts . SoapMethodDispatcher”opera tionNS=” ht tp : / / soa pin te rop . org /”operationName=”exampleMethod”u r l =” h t t p : / / l o c a l h o s t : 9 0 0 0 ”

/ >

< / s e r v i c e >

Listing A.7: SOAP Service Transport Protocol Conguration Example




< s e r v i c ename=”mqService”

>

< connec torcl as s=”com. cre ate tan k . e lemenope . exte ns io ns . mqse ries . t ran sp or ts . MQSeriesConnqueueManager=”QMEXAMPLE”

queueName=”exampleQueue” jmsTarget=” f a l s e ”imsBridgeTa rget=” f a l s e ”transportType=”BIND”

/ >

< brokercl as s=”com. cre ate tan k . e lemenope . exte ns io ns . mqse ries . t ran sp or ts . MQSeriesBrokoperat ionGroup=”exampleOperat ions”queueName=”exampleQueue”sessionAcknowledgementMode=”AUTO”sessionCount=”5”

/ >

< d i s p a t c h e r

cl as s=”com. cre ate tan k . e lemenope . exte ns io ns . mqse ries . t r an sp or ts . MQSeriesDispqueueName=”exampleQueue”

/ >

< / s e r v i c e >

Listing A.8: MQSeries/WebsphereMQ Service Transport Protocol Conguration Example





< operat ionGr oup name=”bpmOperations” >

< ope r a t i onname=”bpmExample”cl a s s=”com. cr ea te ta nk . elemenope .bpm. ElemenopeAsyncBpmChainOperation”

op er at io nL is t=”exampleServiceA:exampleOne , exampleServiceB:exampleTwo”/ >


< operat ionGroup name=”exa mpleOpera t ionsSer viceA ” >

< ope r a t i oncl as s=”org . e lemenope . examples . oper at i on s . ExampleOperation”name=”exampleOne”

/ >


< operat ionGroup name=”ex ampleOpe rat ions Service B” >

< ope r a t i oncl as s=”org . e lemenope . examples . ope ra t io ns . Operat ionTest ”name=”exampleTwo”

/ >< /operat ionGroup >


Listing A.9: ElemenopeAsyncBpmChainOperation Conguration Example




A.2.2 ElemenopeProcessListOperation

This is a very simple implementation which allows only operations within the conguredoperationGroup to be a part of the process list. It returns a List of all responses from all

Operations congured in the operationList.



< ope r a t i onname=”bpmExample”cl as s=”com. cre ate tan k . e lemenope .bpm. ElemenopeP rocess ListO perat iooperat ionGroup=”exampleOperat ions”op er at io nL is t=”exampleOne , exampleTwo , exampleThree”

/ >


< operat ionGroup name=”example Operat ions ” >

< ope r a t i onname=”exampleOne”cl as s=”org . e lemenope . examples . ope ra t i ons . ExampleOperation”

/ >

< ope r a t i onname=”exampleTwo”cl as s=”org . e lemenope . examples . ope ra t i ons . Operat ionTest ”

/ >

< ope r a t i onname=”exampleThree”cl as s=”org . e lemenope . examples . ope ra t i ons . ExampleOperation”

/ >


<

/ o p e r a t i o n s>

Listing A.10: ElemenopeProcessListOperation Conguration Example

ElemenopeProcessListOperation Attributes

operationGroup The operationGroup which contains all operations cong-ured in the operationList attribute.

operationList The list of operations which the BPM is to execute. This listis comma-delimited with no spaces. Each entry in the list is a conguredoperation name from within the congured operationGroup.




A.2.3 ElemenopeProcessChainOperation

This is a very simple implementation which allows only operations within the conguredoperationGroup to be a part of the process chain. It returns a single response from all

Operations congured. Each Operation within the operationList passes its return value tothe next Operation in the list as its input value.



< ope r a t i onname=”bpmExample”cl as s=”com. cre ate tan k . e lemenope .bpm. ElemenopeProcessChainOperat ioperat ionGroup=”exampleOperat ions”op er at io nL is t=”exampleOne , exampleTwo , exampleThree”

/ >


<

operat ionGroup name=”example Operat ions ”>


/ >


/ >

< ope r a t i onname=”exampleThree”cl as s=”org . e lemenope . examples . ope ra t i ons . ExampleOperation”

/ >

< /operat ionGroup >< / o p e r a t i o n s >

Listing A.11: ElemenopeProcessChainOperation Conguration Example

ElemenopeProcessChainOperation Attributes

operationGroup The operationGroup which contains all operations cong-ured in the operationList attribute.

operationList The list of operations which the BPM is to execute. This listis comma-delimited with no spaces. Each entry in the list is a conguredoperation name from within the congured operationGroup.




A.2.4 ElemenopeBpmListOperation

This BPM Operation implementation allows conguration of a process list which spansmultiple services. Like the other “list” implementations, it returns a List of all responses

from all Operations congured in the operationList.



< ope r a t i onname=”bpmExample”c l a s s=”com. c re at et an k . elemenope .bpm. ElemenopeBpmListOperation”operat ionList=”exampleServiceA:exampleOne ,

exampleServiceB:exampleTwo ,exampleServiceB:exampleThree”

/ >


< operat ionGroup name=”ex ampleOper at ionsSer viceA ” >


/ >


< operat ionGroup name=”ex ampleOp erat ions Service B” >


/ >

< ope r a t i onname=”exampleThree”

cl as s=”org . e lemenope . examples . ope ra t i ons . ExampleOperation”/ >



Listing A.12: ElemenopeBpmListOperation Conguration Example

ElemenopeBpmListOperation Attributes

operationList The list of operations which the BPM is to execute. This listis comma-delimited with no spaces. Each entry in the list is in the formof service:operation.




A.2.5 ElemenopeBpmChainOperation

This BPM Operation implementation allows conguration of a process chain which spansmultiple services. Like the other “chain” implementations, it returns a single response from

all Operations congured. Each Operation within the operationList passes its return valueto the next Operation in the list as its input value.



< ope r a t i onname=”bpmExample”c l a s s=”com. cr ea te ta nk . elemenope . bpm. ElemenopeBpmChainOperation”operat ionList=”exampleServiceA:exampleOne ,

exampleServiceB:exampleTwo ,exampleServiceB:exampleThree”

/ >

<

/operat ionGroup>

< operat ionGroup name=”ex ampleOper at ionsSer viceA ” >

< ope r a t i oncl as s=”org . e lemenope . examples . ope ra t i ons . ExampleOperation”name=”exampleOne”

/ >


< operat ionGroup name=”ex ampleOp erat ions Service B” >

< ope r a t i oncl as s=”org . e lemenope . examples . ope ra t i ons . Operat ionTest ”name=”exampleTwo”

/ >

< ope r a t i on

cl as s=”org . e lemenope . examples . ope ra t i ons . ExampleOperation”name=”exampleThree”/ >



Listing A.13: ElemenopeBpmChainOperation Conguration Example

ElemenopeBpmChainOperation Attributes

operationList The list of operations which the BPM is to execute. This listis comma-delimited with no spaces. Each entry in the list is in the formof service:operation.




stagingArea Directory where les will be placed during process of ingestion• required: YES (must be a directory)• default: none

lenameOnly Boolean switch to congure whether the operation returns onlythe lename, or the entire le as a byte array.

• required: no• default: FALSE

deleteFile Boolean switch to congure whether the operation will delete thele after ingestion (only used when lenameOnly is set to FALSE, i.e.when the entire le is returned)

• required: no• default: FALSE

archivePath Directory where les will be placed after staging, but prior toingest (le will be renamed to lename -yyyyMMdd-hhmmssSSS) (mustbe a directory)

• required: no• default: empty (no archival)

leFilterExtensions Comma-delimited list of extensions of les which are tobe ingested

• required: no• default: empty (no le ltering [all les are accepted])• note: Operation only checks whether the le ends with the cong-

ured letters (case-insensitive) — there is no requirement for numberof letters or “dot” seperator.

A.4 elemenope Standard Conguration Maintenance Loop

Prior to the 5.0 release of elemenope, users needing conguration parameters and/orcyclical processing integrated into the elemenope Framework were required to extend theElemenopeStandardConfiguration class. The user would simply override the userInit() ,userShutdown() , and maintain() methods, implementing whatever functionality wasneeded therein. The maintain() method is often put to particular good use as a methodto ingest or process data periodically, as it is available to the system.




public void maintain (){

// c a l l t h e s t an da rd i mp le me nt at io n t o p au se t h e n e ce s sa r y c o n fi g u re d m i l l i ssuper ( ) ;

// c he ck f o r a v a i l a b i l i t y o f new f i l e s h er e . . ./ / . . .

}

Listing A.15: Example Implementation of Maintain Method

A.5 Spring Framework Conguration and Integration Withinelemenope

Subsequent to the 5.0 release of elemenope, users are enabled to utilize the power of the

Spring Framework to handle congurations and integrate Spring Framework capabilitiesinto their elemenope applications. For detailed use, please refer to §5.2. For a very simpleexample see listings A.16 and A.17.

publ ic c l ass ExampleConfigurat ion {

private S t r i ng conf i gAt t One ;private St r i ng conf igAttTwo ;pr iva te in t conf igAt tThree ;

public void se tConf igAt tOne( St r i ng conf igAttOne) {th i s . conf igAt tOne = conf igAt tOne ;

}

public void se tConf igAt tTwo( St r i ng conf igAttTwo) {th i s . configAttTwo = configAttTwo ;

}

public void se tConf igAt tThree ( int conf igAt tThree ) {th i s . conf igAt tThree = conf igAt tThree ;

}

/ / more here . . .}

Listing A.16: Very Simple Conguration Bean Example




< beans >

< bean id=”exampleBeanConfig”cl as s=”your . package . ExampleConfigurat ion ”

>

< prope rty name=”config AttOne” valu e=”v alue1 ” / >

< prope rty name=”configAttTwo” valu e=”va lue2 ” / >

< proper ty name=”conf i gAt tThree” va lue=”value3 ” / >

< /bean >

Listing A.17: Very Simple Spring Conguration Example



Appendix B

FAQ

To ask a question not addressed here, please email us at [email protected]

What does the elemenope Framework offer me? Transport abstraction, functionalabstraction, payload abstraction, fault tolerant messaging, and transport protocolimplementations out of the box.

Who might use elemenope and why? The following roles might use elemenope:

• An integration team or engineer working to connect disparate systems in amanner that lends clean and simple future expansion.

• An engineer or team creating a new application or system, interested in simpli-ed maintenance, and possible future distribution of components without codechanges.

What is transport abstraction, and how does elemenope handle it? Transport ab-straction:

• Provides nearly unlimited scalability, as components may be connected in unex-pected ways at a later date with no changes to code. For example, a team couldconnect a system entirely via direct call transports on a single machine, andwhen load or functionality increases in the future, can move to a completely dis-tributed system by changing the conguration to use JMS (e.g. WebSphereMQ,JBossMQ, ActiveMQ, etc.) on multiple machines, without any change in code.Additions and changes to a single conguration XML le are all that are neededto do this.

• elemenope is open source, free software [GPL and Apache License Version 2.0],and a team may therefore implement their own Connectivity classes (Connector,Broker, and Dispatcher interfaces) in order to implement an entirely new proto-col which will also work transparently with all other elemenope interfaces. This

59



APPENDIX B. FAQ 60

frees up organizations to do anything that they need to do with their systems.For example, an organization might have a need to connect via CORBA withlegacy applications (CORBA is not currently implemented w/in elemenope).They may do this fairly easily, implementing the elemenope connectivity inter-faces. These new connectivity implementation objects may then be referred tow/in the XML conguration le, and the new protocol may be used transpar-ently within the elemenope framework.

What transport protocols does elemenope implement? elemenope currently imple-ments the following service transports:

1. Java Message Service [JMS]2. SOAP Web Services (SOAP extension)3. XML-RPC Web Services4. Direct Call5. Native IBM MQSeries (WebSphereMQ) (MQSeries extension)6. Mainframe connectivity classes (MQSeries extension)

What is functional (business logic) abstraction, and how does elemenope handle it?Functional or business logic abstraction:

• Allows subject matter experts to write simple code without knowledge of thetransport protocol to be employed. This means that one need not know howspecically to connect to MQSeries via JMS, or how to connect to a mainframe,but rather knowledge of the processing to be done.

• Provides uniformity of functional code w/in a project or integration effort. This

helps in logging, metrics gathering, and problem tracing, as all operations w/ina system pass through the same or very similar processing paths.

• Provides ability to dynamically change the combinations of functional code unitsexposed as services under different transport protocols. This allows a systemsengr. for example to open certain dened operations under SOAP, certain othersunder XML-RPC, and all operations under local direct call connectivity.

What is payload abstraction, and how does elemenope handle it? Payload abstrac-tion provides the ability to send either XML or Java Objects (or even other payloadtypes) over the elemenope framework transparently. For example, one might denean Operation class (the functional unit) which expects a particular Java Object. An-

other application written in Python might have a need to call it with XML datawhich validates to a common XML schema [XSD]. the doppelganger extension to ele-menope allows this to work transparently, as the XML is automatically unmarshalledto a Java Object as expected, and the processing occurs with no complaint. This can



APPENDIX B. FAQ 61

also work in the opposite direction, that is, a Transaction which expects XML, butreceives a Java Object may also process data as normal, because the doppelgangerextension will automatically convert the Java object to the expected XML format.

How does elemenope implement Fault Tolerant messaging? Within elemenope, dis-patcher Failover [DFO] provides ability to transparently failover from one transportprotocol to another upon failure with no changes to the functional code or businesslogic. For example, If a direct call connection is preferred, but for some reason thedirect call interface is down or throws an exception, elemenope may easily be cong-ured to provide transparent failover. That is, when an application or user makes thecall, elemenope will rst attempt the direct call interface, and detecting failure, willautomatically and transparently failover to a JMS queue, to be picked up wheneverthe other machine or service is available, thus persisting an important request.

Is there an email list to which I can subscribe for announcements and discussion?Yes there is. It is the elemenope-discuss list. More details and subscription informa-tion can be found at: http://elemenope.org/mailman/listinfo/elemenope-discuss_elemenope.org

This is a fairly low traffic email list, consisting mostly of announcements, with occa-sional questions from elemenope users.

Is there a tutorial or HOWTO document available to start using the elemenope framework?Currently, there is not a document available. It is on our todo list, but has yet tomaterialize. There are two documents available, which are greatly out of date, andshould certainly be avoided. Currently, it is best to direct any pertinent questions [email protected]

I’m looking for a way to communicate using a variety of protocols - is this elemenope?The elemenope framework was designed to handle using and switching transport pro-tocols transparently.

Does elemenope support point to point (PTP) and publish subscribe (PUB/SUB) messaging?elemenope implements JMS Queue connector sets for simple PTP messaging, and ahigher level publish connector set which allows easier use of PUB/SUB within somemessage oriented middleware (MOM) providers. Specic JMS Topic connector setsare planned, but no date has been set for these.

How does one pronounce “elemenope”? elemenope is pronounced L-M-N-O-P or morespecically \ ”el-em-en-O-’pE \

An audio sample of the proper pronunciation can be found here:http://elemenope.org/audio/elemenope.wav



APPENDIX B. FAQ 62

Can I legally use elemenope on my project? elemenope is released under a dual li-cense. Users may utilize the framework under the GNU General Public License [GPL]or under the Apache License Version 2.0. If there are any questions or concerns aboutthe legality of its use, please contact createTank at [email protected] .



Appendix C

Resources

C.1 Internet Site

The main site for downloads and disemination of information concerning the elemenopeSOA/EAI Framework is http://elemenope.org

C.2 Email Discussion Lists

For user discussion of elemenope, please use the elemenope-discuss list. More details andsubscription information can be found at: http://elemenope.org/mailman/listinfo/elemenope-discuss_elemenope.org . This is a fairly low traffic email list, consistingmostly of announcements, with occasional questions from elemenope users.

C.3 Online FAQThe online version of the elemenope FAQ may be found at http://createtank.com/wiki/index.php?ElemenopeFaq

C.4 Spring Framework

More detailed and very useful information regarding the Spring Framework may be foundat the home of the Spring Framework: http://www.springframework.org/

C.5 createTank Support for elemenope

createTank provides complete commercial support for elemenope. More information maybe obtained via email at [email protected]

63



Appendix D

GNU Free Documentation License

GNU Free Documentation License Version 1.2, November 2002Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 51 Franklin Street, Fifth

Floor, Boston, MA 02110-1301, USA Everyone is permitted to copy and distribute verbatimcopies of this license document, but changing it is not allowed.

0. PREAMBLEThe purpose of this License is to make a manual, textbook, or other functional and

useful document ”free” in the sense of freedom: to assure everyone the effective freedom tocopy and redistribute it, with or without modifying it, either commercially or noncommer-cially. Secondarily, this License preserves for the author and publisher a way to get creditfor their work, while not being considered responsible for modications made by others.

This License is a kind of ”copyleft”, which means that derivative works of the documentmust themselves be free in the same sense. It complements the GNU General PublicLicense, which is a copyleft license designed for free software.

We have designed this License in order to use it for manuals for free software, becausefree software needs free documentation: a free program should come with manuals providingthe same freedoms that the software does. But this License is not limited to softwaremanuals; it can be used for any textual work, regardless of subject matter or whether itis published as a printed book. We recommend this License principally for works whosepurpose is instruction or reference.

1. APPLICABILITY AND DEFINITIONSThis License applies to any manual or other work, in any medium, that contains a

notice placed by the copyright holder saying it can be distributed under the terms of thisLicense. Such a notice grants a world-wide, royalty-free license, unlimited in duration,to use that work under the conditions stated herein. The ”Document”, below, refers to

any such manual or work. Any member of the public is a licensee, and is addressed as”you”. You accept the license if you copy, modify or distribute the work in a way requiringpermission under copyright law.

64



APPENDIX D. GNU FREE DOCUMENTATION LICENSE 65

A ”Modied Version” of the Document means any work containing the Document or aportion of it, either copied verbatim, or with modications and/or translated into anotherlanguage.

A ”Secondary Section” is a named appendix or a front-matter section of the Documentthat deals exclusively with the relationship of the publishers or authors of the Documentto the Document’s overall subject (or to related matters) and contains nothing that couldfall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationshipcould be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

The ”Invariant Sections” are certain Secondary Sections whose titles are designated,as being those of Invariant Sections, in the notice that says that the Document is releasedunder this License. If a section does not t the above denition of Secondary then it is notallowed to be designated as Invariant. The Document may contain zero Invariant Sections.If the Document does not identify any Invariant Sections then there are none.

The ”Cover Texts” are certain short passages of text that are listed, as Front-CoverTexts or Back-Cover Texts, in the notice that says that the Document is released underthis License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may beat most 25 words.

A ”Transparent” copy of the Document means a machine-readable copy, represented ina format whose specication is available to the general public, that is suitable for revisingthe document straightforwardly with generic text editors or (for images composed of pixels)generic paint programs or (for drawings) some widely available drawing editor, and thatis suitable for input to text formatters or for automatic translation to a variety of formatssuitable for input to text formatters. A copy made in an otherwise Transparent le formatwhose markup, or absence of markup, has been arranged to thwart or discourage subsequent

modication by readers is not Transparent. An image format is not Transparent if usedfor any substantial amount of text. A copy that is not ”Transparent” is called ”Opaque”.Examples of suitable formats for Transparent copies include plain ASCII without markup,

Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD,and standard-conforming simple HTML, PostScript or PDF designed for human modi-cation. Examples of transparent image formats include PNG, XCF and JPG. Opaqueformats include proprietary formats that can be read and edited only by proprietary wordprocessors, SGML or XML for which the DTD and/or processing tools are not generallyavailable, and the machine-generated HTML, PostScript or PDF produced by some wordprocessors for output purposes only.

The ”Title Page” means, for a printed book, the title page itself, plus such followingpages as are needed to hold, legibly, the material this License requires to appear in the titlepage. For works in formats which do not have any title page as such, ”Title Page” meansthe text near the most prominent appearance of the work’s title, preceding the beginningof the body of the text.




stated location until at least one year after the last time you distribute an Opaque copy(directly or through your agents or retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the Document wellbefore redistributing any large number of copies, to give them a chance to provide you withan updated version of the Document.

4. MODIFICATIONSYou may copy and distribute a Modied Version of the Document under the conditions

of sections 2 and 3 above, provided that you release the Modied Version under preciselythis License, with the Modied Version lling the role of the Document, thus licensingdistribution and modication of the Modied Version to whoever possesses a copy of it. Inaddition, you must do these things in the Modied Version:

A. Use in the Title Page (and on the covers, if any) a title distinct from that of theDocument, and from those of previous versions (which should, if there were any, be listedin the History section of the Document). You may use the same title as a previous versionif the original publisher of that version gives permission. B. List on the Title Page, as

authors, one or more persons or entities responsible for authorship of the modications inthe Modied Version, together with at least ve of the principal authors of the Document(all of its principal authors, if it has fewer than ve), unless they release you from thisrequirement. C. State on the Title page the name of the publisher of the Modied Version,as the publisher. D. Preserve all the copyright notices of the Document. E. Add anappropriate copyright notice for your modications adjacent to the other copyright notices.F. Include, immediately after the copyright notices, a license notice giving the publicpermission to use the Modied Version under the terms of this License, in the form shownin the Addendum below. G. Preserve in that license notice the full lists of InvariantSections and required Cover Texts given in the Document’s license notice. H. Include anunaltered copy of this License. I. Preserve the section Entitled ”History”, Preserve its

Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modied Version as given on the Title Page. If there is no section Entitled ”History” inthe Document, create one stating the title, year, authors, and publisher of the Documentas given on its Title Page, then add an item describing the Modied Version as stated inthe previous sentence. J. Preserve the network location, if any, given in the Document forpublic access to a Transparent copy of the Document, and likewise the network locationsgiven in the Document for previous versions it was based on. These may be placed in the”History” section. You may omit a network location for a work that was published at leastfour years before the Document itself, or if the original publisher of the version it refersto gives permission. K. For any section Entitled ”Acknowledgements” or ”Dedications”,Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. L. Preserveall the Invariant Sections of the Document, unaltered in their text and in their titles.Section numbers or the equivalent are not considered part of the section titles. M. Deleteany section Entitled ”Endorsements”. Such a section may not be included in the Modied




Version. N. Do not retitle any existing section to be Entitled ”Endorsements” or to conictin title with any Invariant Section. O. Preserve any Warranty Disclaimers.

If the Modied Version includes new front-matter sections or appendices that qualify asSecondary Sections and contain no material copied from the Document, you may at youroption designate some or all of these sections as invariant. To do this, add their titles tothe list of Invariant Sections in the Modied Version’s license notice. These titles must bedistinct from any other section titles.

You may add a section Entitled ”Endorsements”, provided it contains nothing butendorsements of your Modied Version by various parties–for example, statements of peerreview or that the text has been approved by an organization as the authoritative denitionof a standard.

You may add a passage of up to ve words as a Front-Cover Text, and a passage of upto 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the ModiedVersion. Only one passage of Front-Cover Text and one of Back-Cover Text may be addedby (or through arrangements made by) any one entity. If the Document already includes

a cover text for the same cover, previously added by you or by arrangement made by thesame entity you are acting on behalf of, you may not add another; but you may replacethe old one, on explicit permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License give permissionto use their names for publicity for or to assert or imply endorsement of any ModiedVersion.

5. COMBINING DOCUMENTSYou may combine the Document with other documents released under this License,

under the terms dened in section 4 above for modied versions, provided that you includein the combination all of the Invariant Sections of all of the original documents, unmodied,and list them all as Invariant Sections of your combined work in its license notice, and that

you preserve all their Warranty Disclaimers.The combined work need only contain one copy of this License, and multiple identicalInvariant Sections may be replaced with a single copy. If there are multiple InvariantSections with the same name but different contents, make the title of each such sectionunique by adding at the end of it, in parentheses, the name of the original author orpublisher of that section if known, or else a unique number. Make the same adjustmentto the section titles in the list of Invariant Sections in the license notice of the combinedwork.

In the combination, you must combine any sections Entitled ”History” in the variousoriginal documents, forming one section Entitled ”History”; likewise combine any sectionsEntitled ”Acknowledgements”, and any sections Entitled ”Dedications”. You must deleteall sections Entitled ”Endorsements”.

6. COLLECTIONS OF DOCUMENTSYou may make a collection consisting of the Document and other documents released

under this License, and replace the individual copies of this License in the various docu-




Each version of the License is given a distinguishing version number. If the Documentspecies that a particular numbered version of this License ”or any later version” appliesto it, you have the option of following the terms and conditions either of that speciedversion or of any later version that has been published (not as a draft) by the Free SoftwareFoundation. If the Document does not specify a version number of this License, you maychoose any version ever published (not as a draft) by the Free Software Foundation.

ADDENDUM: How to use this License for your documentsTo use this License in a document you have written, include a copy of the License in

the document and put the following copyright and license notices just after the title page:Copyright (c) YEAR YOUR NAME. Permission is granted to copy, distribute and/or

modify this document under the terms of the GNU Free Documentation License, Version 1.2or any later version published by the Free Software Foundation; with no Invariant Sections,no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in thesection entitled ”GNU Free Documentation License”.

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the

”with...Texts.” line with this:with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts

being LIST, and with the Back-Cover Texts being LIST.If you have Invariant Sections without Cover Texts, or some other combination of the

three, merge those two alternatives to suit the situation.If your document contains nontrivial examples of program code, we recommend releas-

ing these examples in parallel under your choice of free software license, such as the GNUGeneral Public License, to permit their use in free software.