Home

PDF documentation

1. when Event name 42 then example doSomething Hello World Notification n new Notification n setSubject testsubject n setMessage testMessage n setRecipient testRecipient ealig tC altel Omen tealetaya A 38 HowTo Events with the OpenEngSB Using the logging service Home Test Client Send Event Page Context Services Current Project foo v logout R org openengsb core common v name foo D D lt helo new Copyright 2010 OpenEngSB Division Vienna University of Technology Licensed under the Apache License Version 2 0 the License you may not use this file except in compliance with the License You may obtain a copy of the License at http www apache org licenses LICENSE 2 0 Unless required by applicable law or agreed to in writing software distributed under the License is distributed on an AS IS BASIS WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND either express or implied See the License for the specific language governing permissions and limitations under the License Tr Tr r r te ite ite ite T oie ite r te T ote Event name 42 example doSomething Hello World Notification n new Notification n setSubject testsubject n setMessage testMessage n setRecipient testRecipient notification notify n 2009 2010 Imprint event Basically this rule reacts on all events when clause log is a helper class
2. 102
3. IF you would like to use security instead you should prefer the following call 45 HowTo Interact with the OPENENGSB Remotely encryptedContent encodedMessage Base 64 and encryped string of the message above encryptedKey encodedKey The encoded key Services Select Instance Y 2 AuditingDomain SJ Example Domain O domain example org openengsb domain example ExampleDomain O exampleService org openengsb domain example ExampleDomain doSomething java lang String N Argument 1 value String Call Edit Service Test a proxy When proxying connector calls you have to provide an answer to every call as the system blocks until it gets an answer You have to send a JSON message containing a type string parameter which can be Object Exception or Void depending on the return argument of the method arg where you simply serialise the Return Object so it can be deserialised into the correct object later and className which gives the exact class that has to be used for deserialisation The request contains a parameter callld which is the name of the queue the answer has to be sent to type Object className org openengsb core ports jms JMSPortTest TestClass NMeGtabataw st Gest eesti yaar ny SL T NEes tea Whenever a call to this proxy is then made a new JMS message will be sent to the receive queue on the destination you entered The exact make up of the message was already described Whe
4. If using BEA WebLogic select Don t scan Checkbox during import of Libraries e Close the window with Ok e Open the sessions folder in the tree and rightclick ActiveMQ select edit 66 HowTo Test Remote Messaging using Hermes JMS Com jms B sessions 2S H E contexts Edit a session e Select ActiveMQ in the Loader Dropdown if you don t see the entry ActiveMQ then you probably did not select Scan in the Alertmessage above Connection Factory hermes INDIConnectionFactory ActiveMQ Property ActiveMQ Select the previously configured loader e Select org apache activemq ActiveMQConnectionFactory in the Class dropdown Rightclick on properties and select Add Property Select brokerURL as the property name and enter tcp localhost 6549 this is the standard jms port of the OpenEngSb server enter a different port if you have changed it in your distribution The Entry should now look something like Connection Factory Class org apache activemq ActiveMQConnectionFactory w Loader ActiveMQ v Property Value brokerURL tcp flocalhost 6549 The completely finished entry s Select Ok to close and save e Rightclick on the node ActiveMQ in the sessions folder and select New gt Add Queue 67 HowTo Test Remote Messaging using Hermes JMS amp ims sessions New session gt
5. connector sh in the connector folder You will be asked for the name of the domain you want to implement Enter the domain name starting with a lower case letter You may adapt the name of the implemented domain interface if you it does not match the naming convention Supply the name of the connector staring with a lower case letter The new domain project will be added as a submodule You eventually want to run mvn openengsb eclipse and import the new project in eclipse Implement the domain interface in the supplied class unfortunately no method stubs are generated Unimplemented domain methods should always throw an exception rather than return default value or do nothing Therefore each domain method without body must throw DomainMethodNotImplementedException to indicate that requested domain functionality is not implemented Override joes voice ool 1 throw new DomainMethodNotImplementedException Quickstart The ServiceFactory has to supply a ServiceDescriptor that contains all attributes needed to instantiate the Connector In the methods createServicelnstance and updateServicelnstance use the provided attributes to create a new new instance or update your Connector The methods update Validation and createValidation should do the same but try to validate the provided attributes first and return a validation result The generated ServiceManager usually does not have to be changed Chapter 5 Archit
6. gt mydomain context xml Lahey bundle properties bundle_de properties bundle info pom xml The project contains stubs for the domain interface the domain events interface and the domain provider and a resources folder with the spring setup and property files for internationalization Although the generated domain does in effect nothing you can already start the OpenEngSB for testing with mvn clean install openengsb provision and the domain will be automatically be picked up and started The blueprint setup in the resources folder already contains the necessary setup for this domain to work in the OpenEngSB environment Furthermore the default implementation proxies for the domain interface which forwards all service calls to the default connector for the domain and the default implementation of the domain event interface which forwards all events to the workflow service of the OpenEngSB are configured Each OpenEngSB bundle core domain connector has been designed with localization in mind The Maven Archetype already creates two bundle properties files one for English bundle properties and one for the German bundle_de properties language Each connector has to provide localization through it own properties files For domains this only means localization for a name and description of the domain itself 35 3 Components 1 Domain interface This is the interface that connectors of that domain must im
7. 2 0 SNAPSHOT OpenEngSB maven plugin Version 1 4 0 SNAPSHOT Plugin Assembly version 2 2 beta 5 You will be asked what the groupld artifactId and a name of your client project should look like You can also specify the OpenEngSB version you want to use but it is recommended to use an up to date 41 HowTo Create a Client Project for the OpenEngSB version To check the current OpenEngSB version have a look at the Download section It asks you to confirm the configuration and will create the project 20 5 Step 3 The result If everything worked as expected you will get a client project having following structure openengsb client project assembly Pomem Se Tae ea descriptors Y lonley saul filtered resources ERO org apache karaf features cfg features xml README txt core pom sami SOS homepage pom xml TGT R EE lt manual pom xml shee pom san DICENSE poms compiled gt pom sanil nonosgi To pom xml pom xml wrapped ponam pom xml README md You can find further information about these modules in the OQpenEngS B Manual 20 6 Step 4 Install features To install features to the project have a look at the file org apache karaf features cfg in assembly src main filtered resource etc Here you can define features
8. Domain and Client Tool Connectors are used All of these concepts are explained within the next sections Engineering Service Bus OpenEngSB Client Tool Connectors Domain Tool Connectors Domain Tools Tool Domains ESB Core Components Client Tools Team Communication 00 Client Tool A Client Tool B Team Communication o Tool Data OpenEngSB Infrastructure Technical view of the OpenEngSB highlighting the most important concepts of the integration system 5 1 OpenEngSB Enterprise Service Bus ESB One of the principal concepts for the OpenEngSB development is if possible to use already existing and proven solutions rather than inventing new ones In this manner the OpenEngSB is an extension to the ESB concept Typical ESBs such as Apache Servicemix or other JBI or ESB implementations always have the feeling to be huge and bloated Complex integration patterns messaging huge Architecture of the OpenEngSB configuration files and similar concepts problems lead to this feeling And those feelings are right They are bloated The OpenEngsB tries a different approach Using Karaf as its base framework the environment is VERY lightweight Depending on your use case you can use different configurations and packages out of the box 5 2 OpenEngSB Infrastructure While Apache Karaf provides a rich environment and functionality we re not done with it Via the Apache Aries Blueprint DM e
9. New Context H contexts Duplicate H stores files Discover Delete Strg X Add a queue in hermes e Click on the Name entry and enter receive press ENTER to save your input Hermes JMS is a little buggy here This the standard OpenEngSb receive queue in this OpenEngSb release You must send all your Json messages to this queue e Select Ok to close and save e Now you have to open the queue on which the response of your message will come back In this OpenEngSb release the response queue has the same name as the callId of your message Repeat the steps above and use the callId of your message instead of receive e Now you are ready to send and receive Json Messages to the OpenEngSb Server 26 2 Send and Receive Messages e Startup the OpenEngSb Server before you Startup Hermes JMS or else Hermes JMS might not recognise the server e Expand the node ActiveMQ in the folder sessions and rightclick on the receive queue Select New gt New Message fix xml randomCallid G H 6 contexts stores files Properties Duplicate Create a new Message in Hermes e Switch to the Payload tab and paste your message into the textfield 68 HowTo Test Remote Messaging using Hermes JMS Send message to receive a principal yourusername E credentials className org openengsb connector usernamepas
10. Open up your browser and go to the web interface at http localhost 8090 openengsb Authenticate using the Login link as admin with password password 54 HowTo Integrate services with OpenEngSB Home Test Client Send Event Page Col User Management Services e AuditinaDomain test client Switch to the Test client tab and check whether the build domain is available to accept commands karafGroot gt features install openengsb connector openengsb connector email openengsb connector openengsb connector jira openengsb connector openengsb connector plaintextreport openengsb connector karaf root gt features install openengsb connector maven karaf root gt install connector in console As the build domain is not shown we will need to go to OpenEngSB s console Use the features install openengsb connector maven command to load the tool connector for Apache Maven The tool connector allows OpenEngSB to communicate with an external service or application Maven in this case By loading the connector OpenEngSB also loads the domains associated with the connector A domain is a generic interface that is implemented by specific connectors For example the build domain offers a generic function to build a software project Whether this is done by Apache Maven an Ant script or a plain compiler depends on the connector chosen by the user but does not affect the basic model of our CI tool that simply
11. Page Services Task Overview User Management Workflow Editor Wiring Current Project foo v Logout org openengsb domain auditing AuditingDomain S amp S Globals O auditing Domain endpoints O auditing memoryauditing auditing root Selecting a domain in the drop down field lets globals and endpoints appear 2 You have to choose a global because that is the object you want to get wired with a connector A global variable is part of a rule allowing the workflow service to communicate with connectors and other objects More information you can find in the Chapter about Workflows There are two possibilities to specify a global Either you select one from the list or you write autonomous a name of a global in the corresponding text field If the global doesn t exist there will be a new one created with the type of the selected domain If a global already exists and have another type as selected then there will be an error message after submitting Input field for the global variable 3 You must select a domain endpoint from the corresponding list The list will be loaded after you have selected a domain Input field for the service Id which can be edited by selecting an endpoint from the list 4 You must select the contexts where the wiring shall happen You can select all but at least one have to be selected Information about what a context means can be found at the Context Management List of all available contex
12. The interfaces do not use generic parameters because the benefit is really minimal as the information is erased during compilation There are however abstract classes with generic parameters that make it easier to implement new FilterChainElements 22 Remoting 12 4 Develop an incoming port Incoming ports receive messages and process them using a filterchain There are no restrictions on how the implementation of the incoming port actually looks like Typically an incoming port is an object that spawns a listening thread and uses a filterchain to process incoming messages This is an example of how the incoming port for JMS could look like lt example of a bean representing an incoming port gt lt property name factory gt lt bean class org openengsb ports jms JMSTemplateFactoryImpl gt lt property gt lt property name filterChain gt lt bean factory ref incomingFilterChainFactory factory method create gt lt property gt lt bean gt Every filterchain should use make sure to pass the MethodCall to the RequestHandler in the and using a RequestHandlerFilter 12 5 Develop an Outgoing port Outgoing port implementations must follow a few more guidelines than incoming ports because the OpenEngSB needs to be aware of Outgoing ports present in the system in order to use them in other components like RemoteEvents An outgoing ports is represented as an OSGi service that implements the Out
13. Using the OpenEngSB not only connectors but an entire integrated process workflow and event environment waits for you In addition connectors to different tools can not only be adapted to the specific needs but also simply replaced by other connectors using the Domain concept 3 3 Management Environment The OpenEngSB delivers a complete management and monitoring environment While this environment can be added to your project standalone similar to e g Tomcat management console you also have the possibility to completely integrate the OpenEngSB management environment into your Apache Wicket application 3 4 Simple Development and Distribution Management While typical ESB have to be installed separately from your application the OpenEngSB is delivered with your application Develop your application in the OpenEngSB environment and scripts to embed your application into the OpenEngSB are provided In addition easy blending allows to adapt the OpenEngSB visually to your needs and cooperate design 3 5 Simple Plug Ins and Extensions The OpenEngSB provides the infrastructure for a rich Plug In and extension system Using maven archetypes Plug Ins can be created uploaded and provided to all other OpenEngSB installations or applications using the OpenEngSB Part Il OoenEngSB Framework This part gives an introduction into the OpenEngSB project and explains its base usage environment and the concepts such as Domains Connectors Wo
14. and usability for the storage of relatively small amounts of data with no explicit performance requirements If special persistence features need to be used it is recommended to use a specialized storage rather than the general storage mechanism The persistence service can store any Java Object but was specifically designed for Java Beans With the following additional conditions First of all the bean to persist needs to be serializable In addition the equals method needs to be overwritten If a field on the lhs of the comparision is null every field on the rhs is accepted otherwise the fields are compared dirctly The interface of the persistence service supports basic CRUD create update retrieve delete mechanisms Instances of the persistence service are created per bundle and have to make sure that data is stored persistently If bundles need to share data the common persistence service cannot be used as it does not support this feature The persistence manager is responsible for the management of persistence service instances per bundle On the first request from a bundle the persistence manager creates a persistence service All later requests from a specific bundle should get the exact same instance of the persistence service Queries with the OpenEngSB persistence done via the persistence service Behind this service an easy query by example logic is used to retrieve your results Since the current persistence implementa
15. architecture guide Chapter 5 Architecture of the OpenEngSB 35 1 Prerequisites In case it isn t known what a domain is and how it defines the interface and events for connectors then Section 5 4 OpenEngSB Tool Domains is a good starting point 35 2 Creating a new domain project To get developers started creating a new domain a Maven archetype is provided for creating the initial project structure The openengsb maven plugin see or the etc scripts gen domain sh script which only wraps the invocation of the plug in simplifies the creation of a domain 35 2 1 Using the Maven Archetype It is not recommended to use the maven archetype directly because the genDomain goal of the openengsb maven plugin executes additional tasks i e renaming of the resulting project Furthermore it tries to make sure that the new project is consistent with the naming conventions of the OpenEngSB project The following parameters have to be specified to execute the correct archetype e archetypeGroupld the groupld of the OpenEngSB domain archetype e archetypeArtifactld the artifactId of the OpenEngSB domain archetype e archetypeVersion the current version of the OpenEngSB domain archetype The following parameters have to be defined for the parent of the new domain It is not solely parent of the domain implementation but parent of all connectors of this domain too e groupld the groupld of the project parent Has to be org open
16. e The manual is written as short and precise as possible less text means lesser to read and even lesser to review e The manual does not describe how to use an interface but only coarse grained concepts in the OpenEngSB Since the OpenEngSB is not an end user application but rather a framework for developers we expect that Javadoc is no problem for them Writing Javadoc and keep it up to date is still hard for developers but much easier than maintaining an external document Therefore all concepts are explained and linked directly to the very well documented interfaces in the OpenEngSB on Github To fully understand and use them you ll have to read this manual parallel to the interface documentation in the source code Chapter 2 What is the Open Engineering Service Bus In engineering environments a lot of different tools are used Most of these operate on the same domain but often interoperability is the limiting factor For each new project and team member tool integration has to be repeated again In general this ends up with numerous point to point connectors between tools which are neither stable solutions nor flexible ones This is where the Open Software Engineering Service Bus OpenEngSB comes into play It simplifies design and implementation of workflows in an engineering team The engineering team itself or a process administrator is able to design workflows between different tools The entire description process happen
17. full list of possible commands see the maven bundle plugin documentation lt xml version 1 0 encoding UTF 8 gt lt build gt lt plugins gt lt plugin gt lt groupid gt org apache felix lt groupId gt lt artifactId gt maven bundle plugin lt artifactId gt lt extensions gt true lt extensions gt lt contiguration lt instructions gt lt Import Package gt sun misc resolution optional jJavaxz servlet version 2 5 0 S00 ly resolution optional lt Import Package gt lt instructions gt lt configuration gt lt plugin lt plugins gt lt build gt lt project gt 30 2 Tips and Tricks Although the description above sounds quite simple and wrapping bundles is simple mostly still some nasty problems can occur This section summarizes good tips and ideas how to wrap bundles within the OpenEngSB e The best workflow to wrap a bundle is according to our experiences to execute the previously described steps and simply start the OpenEngSB Either it works or creates a huge stack of exceptions with missing import statements Simply try to fulfill one problem than start again till all references are resolved e Embedding artifacts is nothing bad Although it is recommended to use all references artifacts of a bundle directly as OSGi components it can be such a pain sometimes Some references are simply not required by any other bundle or are too hard to port In such cases feel free to directly embed t
18. integration Whether or not you have experience with CI bear with the tutorial for a moment and you will see how simple it works out Before we get started let us lay out the idea of our CI tool and create a step by step development plan The practice of continuous integration aims at improving software quality by frequent automated building and testing of a project s source base and by reporting back to the developers The CI tool must be able to access the source repository build the project test the binaries and reports to the developers And there we have a basic four step plan 1 Repository access 2 Building source 3 Testing binaries 4 Notification process If you would like to take a look at a fully functional CI server built on OpenEngSB check out OpenCIT It implements a wider range of features but it s a great reference 24 2 Time to Complete If you are already familiar with the OpenEngSB about 30 minutes If you are not familiar with the OpenEngSB please read this manual from the start or check the homepage for further information 24 3 Prerequisites It is assumed you have basic knowledge of software development practices and you are able to set up auxiliary software i e JDK 1 6 yourself Warning This section is likely to change in the near future as the web UI as well as domains and connectors are subject to change 52 HowTo Integrate services with OpenEngSB 24 4 Setting up OpenEngSB s
19. is loaded from the EDB After all loaded data is inserted the user can start work with this model All transformations are done in this service The user doesn t have to worry about that In fact he won t even notice that all this steps were necessary The query service provide a list of possibilities how to load models from the EDB e g based on the model id or based on the key value pairs of the model 33 3 Persist Interface This service has the task to save models to the EDB It transform models into an EDB readable format append informations and forwards the objects to the EDB The PersistInterface consist of three methods namely commit forceCommit and check The commit function performs sanity checks on the models which shall be persisted If they are successfully passed the models are forwarded to the EDB for persisting The forceCommit function forwards the models to the EDB without performing sanity checks The check function only performs the sanity checks and give back the result of the sanity checks 83 Chapter 34 How To Create an Internal Connector This chapter describes how to implement a connector for the OpenEngSB environment A connector is an adapter between an external tool and the OpenEngSB environment Every connector belongs to a domain which defines the common interface of all its connectors This means that the connector is responsible to translate all calls to the common interface to th
20. machine The behaviour of the models are Whenever a model have to transform itself to a list of OpenEngSBModelEntry the model is aware of file objects If it finds a file 719 OpenEngSBModels object it creates a FileWrapper object out of it A FileWrapper object contains the name of the file and a byte array which holds the zip compressed content of the file object If such a FileWrapper would be accessed by a getter of a file object the ModelUtils does the conversion work of the FileWrapper to the file object for you So this feature is completely transparent for the normal user Note that the conversion of a file object to a FileWrapper and the other way round has only to be done if getOpenEngSBModelEntries is called For now this is only the case at two points when a model has to be saved into the EDB or when a model is sent via remote 31 4 Model Ids For easier maintaining and faster finding of models and also to enable the versioning possibility the user is able to define a field to be the id of a model An important point to consider here is that this id has to be unique for a connector of a domain this is because the id will be enlarged with the domain id and the connector id To define a field to be the id of the model you simply have to add an annotation to the corresponding setter The annotation is called OpenEngSBModelld If no id is defined for a model and this model has to be inserted into the EDB the EDB just ta
21. objects which have a list of key value pairs bound to them Also there exist a commit table with which the EDB is able to keep track of all meta data of changes 32 3 Usage An important point to consider is that the EDB isn t supposed to be used directly Instead the EKB Engineering KnowledgeBase component provides two interfaces which shall be used to access the EDB indirectly The reason for that is that the EKB handles the OpenEngSBModels their transformations and everything related to them The EDB on the other hand is only the persistence used by the EKB in the background The saving of models to the EDB directly is conceptionally possible but should always be done through the PersistenceInterface provided by the EKB bundle since this service does the automatic transformation work of elements from OpenEngSBModel to EDB savable objects See the detailed explanation of the EKB for more informations WARNING There was another possibility with which you could throw EDB Events from connectors This possibility is no deprecated and should not be used any more 81 Engineering Database EDB The loading of models from the EDB is conceptionally possible but should always be done through the QueryInterface of the EKB bundle since this service does the automatic transformation work of elements from the EDB to an OpenEngSBModel See the detailed explanation of the EKB for more informations 32 4 Conflict Detection The confli
22. properties gt lt bundle symbolicName gt wrapped_jar_group_id lt bundle symbolicName gt lt wrapped groupId gt wrapped_jar_group_id lt wrapped groupId gt lt wrapped artifactId gt wrapped_jar_artifact_id lt wrapped artifactId gt lt wrapped version gt wrapped_jar_version lt wrapped version gt lt bundle namespace gt L wrapped groupId lt bundle namespace gt lt properties gt lt modelVersion gt 4 0 0 lt modelVersion gt lt groupIid gt wrapped groupId lt groupId gt lt artifactId gt org openengsb wrapped groupId lt artifactId gt lt version gt wrapped version lt version gt lt name gt bundle symbolicName lt name gt lt packaging gt bundle lt packaging gt lt dependencies gt lt all_jars_which_should_be_embedded gt lt dependencies gt 77 Prepare and use Non OSGi Artifacts lt project gt 5 Now add the OSGi specific statements for the maven bundle plugin While the default export and import are already handled in the root pom project specific settings have to be configured here For example all packages within the bundle namespace are always exported This is for most scenarios sufficient In addition all dependencies found are automatically imported as required This is generally not desired Instead the parts of the library which have to be imported should be defined separately The following listing gives a short example how this OSGi specific part can look like For a
23. sends the request via a json encoded JMS message The destination describes the endpoint the message should be sent to When using jms json the domain and port of the JMS provider have to be set When calling a remote connector the unique id 44 HowTo Interact with the OPENENGSB Remotely of the remote service or connector has to be provided This way the remote service can identify load and call a certain service If the call is not intended to go to another OPENENGSB or the external service needs no identification of the service to call the remote service id can be omitted Creating new Proxy for Beispiel Domane Proxy Connector to call external services Service Id lexampleService Port ID jms json Destination _ localhost 6549 Remote Service Id S Validate Service Save Create Proxy After saving the proxy you should be able to test it via the TestClient page Following is an example of an unsecured call authenticationData className org openengsb core api security model UsernamePasswordAuthenticationInfo telias i username admin password password timestamp 42 message eaS Snir Yanswer true TOOT Boe a LE Welassas sl ST lango errime hn org openengsb core api workflow model ProcessBag l methodName executeWorkflow metaData serviceFilter objectClass org openengsb core api workflow WorkflowService context TaS TE O simpleFlow
24. the core components the tool domains finally result in the OpenEngSB 5 5 Client Tools Service Consumer Client Tools in the OpenEngSB concept are tools which do not provide any services but consume services provided by Tool Domains and Core Components instead A classical example from software engineering for a client tool is the Integrated Development Environment IDE Developer prefer to have the entire development environment reaching from the tickets for a project to its build results at hand On the other hand they do not need to provide any services 5 6 Domain Tools Service Provider Domain Tools Service Provider Domain Tools compared to Client Tools denote the other extreme of only providing services Classically single purpose server tools like issue tracker or chat server match the category of Domain Tools best Most tools in software engineering environments fit of course in both categories but since there are significant technically differences between them they are described as two different component types Architecture of the OpenEngSB 5 7 Domain and Client Tool Connectors Tool Connectors connect tools to the OpenEngSB environment They implement the respective Tool Domain interface As Client Tool Connectors they provide a Client Tool with an access to the OpenEngSB services Again Domain and Client Tool Connectors are mostly mixed up but separated because of their technical differences Additiona
25. the dependencies ix cccsisss oes neii ian E esis E E EEE 94 37 6 Step 3 Configure the connector sss serere es rees 94 37 7 Step 4 Implement the connector see ee ee ee eee eee 95 37 8 Step 5 Blueprint Setup and Internationalization sss sese eee eee eee eee eee 99 37 9 Step 6 Start the OpenEngSB with your Connector sese eee eee 100 37 10 Step 7 Test the new Connector ponien n eieiei a e i ee 100 How to add new field support for domain models sss sss see eee 101 SSA AGA E or cate sexes Osuna TT TTT 101 38 25 Time toComplete na en seve latin stedvontsudlla EEE aa E a aa 101 38 3 R S LTTE AR E E E ERTE 101 OpenEngSB Manual 38 4 Subtask 1 Add model support 38 5 Subtask 2 Add EDB support vi Part I Introduction This parts provides general information to the project the document changelog and similar data which fits neither in the framework description nor in the contributor section The target audience of this part are developers contributors and managers Chapter 1 How to read the Manual Like any open source project we have the problem that writing documentation is a pain and nobody is paid for doing it In combination with the rapidly changing OpenEngSB source base this will lead to a huge mess within shortest time To avoid this problem we ve introduced regular documentation reviews and more importantly the following rules which apply both for writing the document and for reading it
26. to be registered by default or which feature should be installed on startup To install your own features see the file features xml in assembly src main filtered resource E G You want to add a module called clientproject ui the core features add this to the features xml lt bundle gt mvn org openengsb clientproject ui clientproject ui web project version war lt bundle gt 42 HowTo Create a Client Project for the OpenEngSB 20 7 Step 5 Start the Client Project To start the client project go to the command window and type mvn clean install openengsb provision Now you can enter list into the karaf console to check what features are installed and running 20 8 Step 6 Shutdown To shutdown go to the command window and type shutdown or press Ctrl D 43 Chapter 21 HowTo Interact with the OPENENGSB Remotely 21 1 Using JMS proxying The current JMS Connector allows for internal method calls being redirected via JMS as well as internal services being called For resources regarding JMS please take a look at the according Wikipedia Page and for specific language bindings take a look at ActiveMQ 21 1 1 Proxying internal Connector calls Whenever now a method is sent through the JMS Port the call is marshalled and sent via JMS to a queue we named receive The marshalling is done via JSON The mapping has the parameters methodName args classes metadata and potentially ans
27. tools z c30 cde ine Ghee elie ieee ddaats 41 204 Step 2 Using the archetype i 2 c04 iow eeeedi wes eee oe tea eai 41 2055 Step 3 2 The tesullt essnee eee hee be Qe eae 42 20 6 Step 4 install features nire urtie ine al ar ee eal ee eae 42 20 7 Step 5 Start the Clrent Project T 43 20 8 Step T IES Le di vesetvaleccid teteiys ide haves del asec lstetss 43 lil OpenEngSB Manual 21 HowTo Interact with the OPENENGSB Remotely sse 44 21 1 Using JMS proxyin i cccss dcsces iobet be veiesecs ie seedeveseedes debe ra a a iie at 44 21 2 Using WS Proxing aiseria reia TTT 48 21 3 Internal Specialities sss v zggota cs Ta diyn yor deb sdeabeccnsnanccececabacdua eiii i i 48 22 HowTo Combine multiple connectors esse ee ee ee ee ee eee 49 22 1 Composite StLAtE TTT 49 22 2 Create a composite CONNECCON sss sees ee ee ee eee 49 23 How to define a domain model eiseres iiaiai E yo ZR TET ETT vr 50 23 1 Goal sive E E ad aac ie A ee Sa es 50 23 2 Time to complete fisi5 ier cage eee ese aE eke ARAE EEEE aE E Wale bee Een 50 23 3 Prerequisites icscs 2 desig tices a ASR eee ate aaah ee deat ee a eis 50 23 4 Step 1 Plan the structure of the model sees 50 23 5 Step 2 Write the model rnein deta ee eke dade svete AE Er idee dhe 50 23 6 Step 3 Add the model to a domain sss sees 51 23 1 Step 4 Use the modeli tiena a e E Ea E TE ESEESE po 51 24 HowTo Integrate services with OpenEngSB sese eee eee eee 52 24 T
28. will be based upon the javax mail libraries we need to include dependencies for the OSGi versions of these artifacts into the pom file located at provision pom xml So we add this dependency to the dependencies section lt dependency gt lt groupId gt org apache servicemix bundles lt groupId gt lt artifactId gt org apache servicemix bundles javax mail lt artifactId gt lt version gt 1 4 4 lt version gt lt dependency gt 37 6 Step 3 Configure the connector To configure the connector as part of the OpenEngSB two more things are necessary At first we have to add the connector to the modules section of its parent pom if it is not already present there If you have run openengsb genConnector in the connector directory this step should have already been performed automatically for you To check or manually add the entry open the file connector pom xml and add the new connector to the modules section 94 HowTo Create a connector for an already existing domain for the OpenEngSB lt modules gt lt module gt email lt module gt lt modules gt The second step is necessary to configure Karaf correctly Please open the file assembly pom xml and add the following line lt profile gt lt id gt release lt id gt lt deployURLs gt scan bundle mvn org openengsb connector org openengsb connector email 2 5 1 lt deployURLs gt 37 7 Step 4 Implement the connector Now you ca
29. 26 Deployer services 14 1 1 Root services Note that root services i e connector services deployed from the etc directory are deployed with a lower service ranking This is done so that normal services are preferred when matching services 14 2 Context configuration The context deployer service creates contexts according to any context files found in the config directory The context id is the file name without the extension The file content will be ignored So for example 27 Chapter 15 Client Projects and Embedding The OpenEngSB Although the OpenEngSB is distributed as a binary ZIP it is basically not meant to be used that way Instead you typically start developing your own project using the OpenEngSB as a base environment and Maven to assembly your code with the OpenEngSB 15 1 Using the same dependencies as the OPENENGSB To use the same dependencies as the OPENENGSB project you have to import the openengsb bundle settings project into your dependency management section lt dependencyManagement gt lt dependencies gt lt dependency gt lt groupid gt org openengsb build lt groupId gt lt artifactId gt openengsb bundle settings lt artifactId gt lt version gt Version of OPENENGSB you use lt version gt lt type gt pom lt type gt lt scope gt import lt scope gt lt dependency gt lt dependencies gt lt dependencyManagement gt This will import all the dependencies with the cor
30. 3 3 21 1 4 Connect With Python To test the OPENENGSB JMS implementation with Python please follow the instructions The example can be downloaded here Connect With CSharp The CSharp connector is written on basis of the Apache ActiveMQ JMS connector There an EngSB sIn file This project file has been developed with SharpDevelop 4 but is also tested with VisualStudio 2008 CSharp Express Edition with the Net Framework 4 The example can be downloaded here Connect With Perl As shown in this example you can connect to the OpenEngSB in a similar way as with Python or CSharp The example can be downloaded here Alternatives for JMS In addition to providing a very general infrastructure we also support the specialities of the various protocols For JMS e g you ve the possiblitiy to make use of the JmsCorrelationId and JmsReplyTo fields If you set the JMSReplyTo field messages will be returned there instead of to the callld In addition if you set a correlationId in your message it will be set in the outgoing message too Otherwise the messageID is now written into the correlationID field 21 2 Using WS Proxing TBW Jira ISSUE 21 3 Internal Specialities Basically there is nothing special to do to get up a service Still since java has no static type information there is no possibility to marshal things like a java util List of options The fix we ve introduced for this problem is to annotate parameters and define a custom mar
31. Choose One v Call Ei o Methodcall called successfully o Result 2c454b27 d9fd 4e80 be0d dbab91330f8d test test connector yes that s necessary We are also going to test the newly created connector Use the tree view at the bottom of the page to navigate to TestDomain and select the tester service In the drop down box below choose runTests and click the Call button If the method called successfully message is returned the Maven connector ran the rigorous unit tests on our sample application and they were passed with flying colors Home Test Client Send Event Page Context User Management org openengsb core common Event name send event page In case you are wondering about the output of the test suite go to the Send Event page There you will find an audit list of all events processed by OpenEngSB and their corresponding payload i e the output of the test run The list behaves like a log file with most recent events appended to the bottom In OpenEngSB any input from connectors is processed by domains and packaged in form of events Every time an event is raised it can be matched by a rule in a central rule base and cause a reaction of the system possibly invoking different domains or spawning additional events By editing the rule base we become able to link different actions together Depending on the outcome of an action we may receive different events i e build success or build failure By cre
32. Create a connector for an already existing domain for the OpenEngSB public EmailServiceImpl String id MailAbstraction mailAbstraction tRLS abick aliclp this mailAbstraction mailAbstraction properties mailAbstraction createMailProperties Perform the given notification which defines message recipient subject and attachments E Override public void notify Notification notification mailAbstraction send properties notification getSubject notification getMessage notification getRecipient see org openengsb core api AliveState E Override public AliveState getAliveState AliveState aliveState mailAbstraction getAliveState if aliveState null return AliveState OFFLINE return aliveState wole Serias Cer ten i return id public ServiceRegistration getServiceRegistration return serviceRegistration public void setServiceRegistration ServiceRegistration serviceRegistration this serviceRegistration serviceRegistration public MailProperties getProperties return properties As you can see without the mail specific stuff the implementation is quite straight forward Simply implement the domain interface as well as the getAliveState method which is used to query to current status of a tool import import import import import import package org openengsb connector email internal java util HashMap java util
33. EngSB about 15 minutes see HowTo Setup 18 3 Prerequisites This HowTo assumes you have already a running instance of the OpenEngSB 18 4 Creating E Mail Services Create a new Email Notification Service by clicking the New link for the Email Notification on the Test Client link o Logging Service Logs messages with a specific log level to the OSGi logger New a o Example Domain Proxy service Proxy service to interact with external services New Services 7 Select Instance 4 BuildDomain domain build org openengsb domain build BuildDomain 3 DeployDomain D domain deploy org openengsb domain deploy DeployDomain SCM Domain domain scm org openengsb domain scm ScmDomain Issue Domain O domain issue org openengsb domain issue lssueDomain K TestDomain domain test org openengsb domain test TestDomain Report Domain D domain report org openengsb domain report ReportDomain Notification Domain domain notification org openengsb domain notification NotificationDomain test1 org openengsb domain notification NotificationDomain test2 org openengsb domain notification NotificationDomain 3 Example Domain domain example org openengsb domain example ExampleDomain Choose One x Call Edit Se U Q a Q Q 2009 2010 Imprint test client In the following view you have the possibility to configure the Notification Service The following screen provid
34. First of all they follow the pattern domain connector instance connector Here domain stands for the domainId to use e g notification connector for the name of the connector which should be created in the domain e g mail and instance is a unique id per connector A simple UUID or a unique counter should do here The content of the file is two fold On one hand you can configure the properties of a service directly using property NAME_OF_THE_PROPERTY VALUE_OF_THE_PROPERTY for example property location root notificaiton Those properties are directly added to the properties of a service On the other hand you have to configure the connectors themselves Therefore you have the attribute NAME_OF_THE_CONNECTOR_ATTRIBUTE VALUE_TO_ASSIGN Throwing this together you can end with a connector file as shown next Example 14 1 Example connector configuration file for the email connector The email connector is regsitered in the root context with the name notify The file name has to be notificaiton email dc110658 c6be 4470 8b4 1 6db154301791 connector which represents a connector instance with the instanceld dc110658 c6be 4470 8b41 6db154301791 of the eemail connector in the notificaiton domain property location root notify attribute user user attribute password test attribute prefix test attribute smtpAuth true attribute smtpSender test test com attribute smtpPort 25 attribute smtpHost smtp testserver com
35. Goal rera e a E e a ea a a iste eerie anes 52 24 2 TIME toComplete rten a E ete Rie eae bees 52 2453 PLETEGUISITES erneer eriet ea ets gas E aE E a a a ee 52 244 Settine up OpenEneSB rreson Giada E RE E ER AEREE EA 53 24 5 Step 1 4 So rce TEPOSILOLY TTT 54 24 6 Step 2 Building the source code sss sese ee eee eee 54 2AT Step 3 Testing DM aries tececessencocchiescascsdededesks seeped iharecscdtepeccesdendosets E a a AaS 57 24 8 Step 4 Notification Process c isssicisreciisriricsiireriiiirriieciricereeiirriserirreesiersrs 59 24 9 Further Reading s25 ezsesivesbatetewtsuectuaisies ata a eeo ae aa a Ata lads r eaaa aiite 61 25 HowTo Change EDB database back end sese sese 62 S GO aly T 62 25 2 Tim t Complete scenerie iii i ii a iei ti t a e 62 25 3 Use JPA compatible database sss sees 62 25 4 Use non JPA compatible database sss sees eee 63 25 5 Appendix Use no OSGi compatible database sss eee 63 26 HowTo Test Remote Messaging using Hermes JMR 64 26 1 Preparation nenoaii een a E E E EAE i eee orn wees ae R 64 26 2 Send and Receive Messages 0 eceeesececececececececececececececececececececeeeeeeeeseeeeens 68 Ti Administration Console isos az cars vee ZE T RE sted aed ieee a EEE ee aes TE tek eventos 70 27 OpenEngSB console COMMANAS a daze e d CYS dh a TRE TEE 9 d CEE d 29 ii 71 27 1 Start the console casare ivedesivenses A E E R Saeko EA Avekee Sede e vee 71 27 2 Available Commands donosa Cai EE
36. L Punctiona lity lt tc sin Sees ea a e ati ees SU ies es Gs Sb aes Ue ose oh 19 V2 REMOUIN Gc EAA TH ea let areas Mlsiias oh dale T 20 TQ AVP iters tee tee et ea ht ahaa Penh a Ae oe Aree tA ta ta hee Set Beall rent 20 12 2 Configure a filterchaime onii ei tac alivettegecie a a en eE n thdeale iaaa 22 ii OpenEngSB Manual 12 3 Develop customs filters arcena aean iaag a weit cb a aii ia 22 12 4 Develop an incoming pott sss sse eee e eee eee 23 12 5 Develop an Outgoing Port esse sees eee eee 23 13 External Domains and Connectors sss sese eee eee 25 T31 Prox yin eis ce 2ecndeeckata doe bea ceded aa aee eae A cede asd aa e aaea TTT 25 14 Deployer S rviCes Kada ckS be del KERVERN ROO KROZ a 26 14 1 Connector configuration sese eee eee 26 14 2 Context Configuration TTT 27 15 Client Projects and Embedding The OpenEngSB sss esse sese eee eee 28 15 1 Using the same dependencies as the OPENENGSB see 28 16 OpenEng SB Platformi re ori ac igeshy tates tel aasiate eden teen a anaa iea aii 29 17 HowTo Setup OpenEngSB for development First steps sese 30 Wil Goal cin accsue Yeh Geel ahi eee eh et 30 17 2 Time to Complete rerin errenta E A ERE ETE 30 17 3 R U arire pirid eE 12 E ue Se A EEA E R eei aR Eies 30 17 4 Java Development Kit Gurerrer einer enorit ara a E a ie 30 17 5Getting OpenEngS TTT 30 17 6 Installing OpenEngSB irern cT gsS2y trenirat aee ea Eea E Eia 30 17 7 Setup required a eT 31 17 85 First Steps e
37. Map org openengsb connector email internal abstraction MailAbstraction org openengsb core api ServiceInstanceFactory org openengsb core api descriptor AttributeDefinition org openengsb core api descriptor ServiceDescriptor 96 import import import public HowTo Create a connector for an already existing domain for the OpenEngSB org openengsb core api validation MultipleAttributeValidationResult org openengsb core api validation MultipleAttributeValidationResultImpl org openengsb domain notification NotificationDomain class EmailServiceInstanceFactory implements ServiceInstanceFactory lt NotificationDomain EmailServiceImpl gt private final MailAbstraction mailAbstraction public EmailServicelInstanceFactory MailAbstraction mailAbstraction this mailAbstraction mailAbstraction private void setAttributesOnNotifier Map lt String String gt attributes EmailServiceImpl notifier if attributes containsKey user notifier getProperties setUser attributes get user if attributes containsKey password notifier getProperties setPassword attributes get password if attributes containsKey prefix notifier getProperties setPrefix attributes get prefix if attributes containsKey smtpAuth notifier getProperties setSmtpAuth Boolean parseBoolean attributes get smtpAuth if attributes containsKey smtpSender not
38. OpenEngSB Manual Table of Contents I Tintroduicti Onn enner aeieea aa dish sca aeiia er eiea iaa ielea ia aa eae 1 1 How to read the Nana sss ggzgchs ddc odi dior dodi ii a e eE 2 2 What is the Open Engineering Service BUS see eee ee eee 3 3 When to use the OpenEng 1 srneci ethers Sieh aa aea e atr degen ENA 4 3 1 The OpenEngSB as Base Environment sese ee eee ee eee 4 3 2 Reusing integration Components and Workflows sss sese ee eee e e e e e e eee 4 3 3 Management Environment TT 4 3 4 Simple Development and Distribution Management sese eee eee eee 4 3 5 Simple Plug Ins and Extensions 0 0 0 0 reve es reter rs corre rere ee ranr gere ry 4 Tl OpenEngSB Framework lt lt eras cies Gti E e e 2R2 eee ATOS y OT az EEE TETA Ta an 5 A R a a EEEE E I NEE RE EAEE PEOI AE EI E E EE A ET 6 4 1 Writing new projects using the OpenEngSB esse ee ee ee ee eee eee 6 4 2 Writing Domains for the OpenEngSB sss ice ee eee e eee 6 4 3 Writing Connectors for the OpenEngSB eee eee eee 6 5 Architecture of the OpenEngSB nnrir setae ieee teda eiea a ipia eea ete eden 8 5 1 OpenEngSB Enterprise Service Bus ESB sese eee 8 5 2 Open Eng SB Infrastructure iaco scg tcetetsrechsdshtivegelst pea aattacaseldtees odaatheadeadteeesalgeaeeeelste 9 5 3 OpenEngSB Components st cocciisees cdseticeccasepensendetcocetasbehedagsbewsedtapeceehbetcocsbeneesedans 9 5 4 OpenEngSB Tool Domains 552974 Ta S297927 Ta 2929 Z KOI TRY 2972944 Ta R29 4 KOZ 54 9 5 5 Clie
39. SB supports the modeling of workflows This could be done by two different approaches First of all a rule based event approach by defining actions based on events and their content which were thrown in or to the bus Events are practical for short time handling since they are also easy to replace and extend For long running business processes the secondary workflow method could be used which is based on Section 10 3 Processes described in Drools Flow The workflow service takes events as input and handles them using a rulebased system JBoss Drools It provides methods to manage the rules The workflow component consists of two main parts The RuleManager and the WorkflowService 10 1 Workflow service The workflow service is responsible for processing events and makes sure the rulebase is connected to the environment domains and connectors When an event is fired the workflow service spawns a new session of the rulebase The session gets populated with references to domain services and other helper objects in form of global variables A drools session is running in a sandbox This means that the supplied globals are the only way of triggering actions outside the rule session 10 2 Rulemanager The rule manager provides methods for modifying the rulebase As opposed to plain drl files the rulemanager organized the elements of the rulebase in its own manner Rules Functions and flows are saved separately All elements shar
40. T A ets abate des e a deis 71 TV Administration User a Te T 72 28 TEStCHE ME TT 73 28 1 Managing global variables sd zco ceceeeeeeecececececeeecececececececenececeaeeeeeeeeeaeeeaeas 73 28 2 Managing IMPOTS esei tereni ee aa ile eee a ie ees 73 29 WATLING ccs eren E oct Marc Saeue Vad depen de E goth a o E sures tebecen Ss oats sychev ea Teed vanes EE a 74 29 1 Wire a global variable with a service see ee eee eee 74 29 2 What wiring does in the background sese sese eee 75 V OpenEngSB Contributor Detail Informations sss sese sese ee ee ee ee ee ee ee ee ee eee eee 76 30 Prepare and use Non OSGi Artifacts see eee 77 OpenEngSB Manual 31 32 33 34 35 36 37 38 30 1 Create Wrapped Artifacts TT TT 3022 Tips and Tricks sinso disni eria e ESEESE ari asa Va O Ta 78 OpenEngSBModels saz z g e Eadair 2 ne deb EO oc akir iiaa a EK KESE NERE i ee 79 SILT Motivation TTT ee eed dua eases ee 719 31 2 Structure of a model ccc cccis cesses becccseee bebsdesbedsohebe ceesnondveconsesdensbensvdeonsascenns 79 31 3 Supported field typ s snscicsiinseisieisesersisori esite anD Ca hE 79 314 Model TdS TTT 80 Engineering Database EDB nosies arion naa o a ot ia a Vaas baa 81 32 1 Motiva Onine nena eaa eaea ENE EEE A E E EARNE 81 PAPAE Te HTH 81 323p TTT E E EE EEEE E EAER 81 32 4 Contlict Detection i oiee ac aiie iasa EEEE SEEE EEE EAE Vaa Erebara 82 Engineering Knowledge Base EKB ee 83 33 1 Moti
41. The callld however cannot necessarily be extracted from the plain text message at the beginning of the chain Therefore a map containing values obtained in the filter chain propertyContainer is passed in to each filter during processing 21 Remoting This is only a specific example of creating a port Another port behaving similarly but using xml as encoding can easily be configured It can use the same bean but with a different filterchain In the filterchain the first element is replaced by an XMLMethodCallMarshalFilter the RequestHandlerFilter is the same as in the jms json port 12 2 Configure a filterchain An instance of FilterChainElement may only be part of one FilterChain In order to reuse FilterChainElements in other filterchains new instances must be created This is because the instances of the filters may contain references to the next element in the chain That s why Filterchains are supposed to be configured using a FilterChainFactory A filterchain is a bean configured with a list of filters Each element may either be the Classname of a FilterAction class which must have a public default constructor or an instance of a FilterChainElementFactory The last element in the list may also be an instance of a FilterAction or other FilterChain The following example shows how to configure a port via blueprint lt bean id incomingFilterChainFactory class org openengsb core common remote FilterChainFactory gt lt p
42. all and Open Hermes it is better to have the OpenEngSb server already running at this point e Rightclick on the node sessions in the tree go to New gt New Session 64 HowTo Test Remote Messaging using Hermes JMS HermesJMS hermes hermes config xml File Messages Actions Options Help ici m ARI EAA AoA Sie 29 9 xX BS BER A New Message Edit Properties feat Seizet Create new JMS session f Add queue Duplicate Add topic Add Session s In the First Dropdown enter ActiveMQ Preferences Use Consumer Transacted v Default Property Value Enter Name for Session s Click on the Tab Providers Available Tabs e Rightclick in the center of the Classpath Groups panel Select Add Group and enter ActiveMQ e Click on the new Group ActiveMQ and rightclick Libary select Add Jars Go to ActiveMQ HOME lib and select all contained jars It should now look something like 65 HowTo Test Remote Messaging using Hermes JMS Preferences ClasspathGroups ClasspathGroups containing JMS providers and dependent libraries Classpath Groups ActiveMQ Library F Programme apache activemg 5 5 1 lib activation 1 1 jar F Programmelapache activemg 5 5 1 lib activemg camel 5 5 1 jar F Programme apache activemg 5 5 1 lib activemg console 5 5 1 jar F Progr
43. amme apache activemg 5 5 1 lib activemg core 5 5 1 jar F Programme apache activemg 5 5 1 lib activemg jaas 5 5 1 jar F Programme apache activemg 5 5 1 lib activemq protobuf 1 1 jar F Programme apache activemg 5 5 1 iblactivema rar txt F Programme apache activemg 5 5 1 lib camel core 2 7 0 jar F Programme apache activemg 5 5 1 lib camel jetty 2 7 0 jar F Programme apache activemg 5 5 1 lib camel jms 2 7 0 jar F Programme apache activemg 5 5 1 lib camel spring 2 7 0 jar F Programme apache activemg 5 5 1 lib geronimo j2ee management_1 1_spec 1 0 1 jar F Programme apache activemg 5 5 1 lib geronimo jms_1 1_spec 1 1 1 jar F Programmelapache activemg 5 5 1 lib geronimo jta_1 0 1B_spec 1 0 1 jar F Programme apache activemg 5 5 1 lib jaxb api 2 1 jar F Programme apache activemg 5 5 1 lib jaxb impl 2 1 6 jar F Programme apache activemg 5 5 1 lib jcl over slF4j 1 5 11 jar F Programme apache activemg 5 5 1 lib kahadb 5 5 1 jar F Programme apache activemg 5 5 1 lib slF4j api 1 5 11 jar F Programmelapache activemg 5 5 1 lib stax 1 2 0 jar F Programme apache activemg 5 5 1 lib stax api 1 0 1 jar List of AMQ libraries e IMPORTANT An alert message is prompted select Scan Please choose p Hermes will scan the JARs for JMS connection Factories when you confirm this dialog wy You only need to do this if you re not using INDI and it can take some time if the library is very large
44. an interface which extends the OpenEngSBModel 23 2 Time to complete If you are already familiar with the OpenEngSB about 10 minutes If you are not familiar with the OpenEngSB please read this manual from the start or check the homepage for further information 23 3 Prerequisites For information about how to get started as contributor to the OpenEngSB project and how to get the current OpenEngSB source please read the contributor section of the manual Part V OpenEngSB Contributor Detail Informations 23 4 Step 1 Plan the structure of the model The first thing to do is to think about the structure of the model you need Think about which informations are needed and should be included e g if you want to create a domain model for an appointment domain the domain model will contain informations like start time end time title Also give a think about if there exists a field which has the potential to be the id of a model Such a field has to be unique for a specific domain and connector combination Such an id can be defined through an annotation with the name OpenEngSBModel 23 5 Step 2 Write the model Writing a model is quite simple A domain model is an interface which contains only pairs of getter and setter methods The method names define the internal names of the fields of the model Example model interface Appointment extends OpenEngSBModel OpenEngSBModelld void setId Integer id Integer getI
45. at the archetype will use the artifactId to name the project but the OpenEngSB convention is to use the connector name Therefore you will have to rename the resulting project however if you use the genConnector mojo this renaming will be performed automatically Do not forget to check that the new connector is included in the modules section of the domain parent pom xml file 34 2 2 Using mvn openengsb genConnector Simply invoke mvn openengsb genConnector from the connector directory connector alternatively the etc scripts gen connector sh script can be used which invokes the openengsb maven plugin for you connector mvn openengsb genConnector The mojo tries to guess as much as possible from your previous input Guessed values are displayed in brackets If the guess is what you want simply acknowledge with Return The following output has been recorded by executing the script in the connector directory Domain Name domain notification lt Enter gt Domain Interface NotificationDomain lt Enter gt Connector Name myconnector twitter lt Enter gt Version 1 0 0 SNAPSHOT lt Enter gt Project Name OpenEngSB Domains Notification Twitter lt Enter gt Only the domain and connector name was set everything else has been guessed correctly After these inputs are provided the Maven Archetype gets called and may ask you for further inputs You can simply hit Return each time to acknowledge standard
46. ateEvent EDBDeleteEvent and EDBBatchEvent to the EDB where they will be saved updated or deleted This events can be thrown from every connector that extends AbstractOpenEngSBConnectorService which shall be done by all connector implementations An OpenEngSBModel consists only of getter and setter pairs Those methods describe which fields the model have Field types which are supported until now are simple types Strings Date OpenEngSBModel Lists and Files Files are a special case but it is possible to send models with File objects remotely and the File which is represented by the File object will be available at the remote machine as a local copy there Every OpenEngSB Model can define an id for itself This id can be used for easier finding of domain models and to enable the versioning possibility when they are saved in the EDB Such an id can easily be defined by setting a special annotation over the setter which defines the id for the object This annotation is called OpenEngSBModelld 6 2 Load Domain Models Domain models can be loaded from the EDB through the EKB The EKB bundle provides a service called QueryInterface This service provides all needed functionality to search and load models from the EDB It also convert the elements from the EDB to a new instance of the domain model you request 6 3 Model Transformation This feature is not yet implemented There is currently research going on how to accomplish this task t
47. ating separate rules for each case we can react accordingly and by chaining multiple actions and events we could create a longer decision tree or process model 58 HowTo Integrate services with OpenEngSB 24 8 Step 4 Notification Process In the final step we link the build and test stages together and add functionality to output results of the process For this purpose we will create a small number of rules that react to events generated by the build and test stage To keep things simple we do not add further connectors and assume that the build process is started by calling the builder s build method in the Test client web UI We are going to write the results of the build and test stage to the management console of OpenEngSB We will notify about the build starting and its outcome Also in case the build works out successfully we will automatically start the test process Hence we need rules matching BuildStartEvent and BuildSuccessEvent that write output to the console and potentially activate the test connector Rule ofg openengsb auditEvent new save cancel Copyright 2010 OpenEngSB Division Vienna University of Technology Removed for the tutorial when e Event then auditing audit e toString rule base editor The easiest way to edit the rule base of our OpenEngSB instance is the editor area at the bottom of the Send Event page You can find event types and names b
48. builds the source Using this technique specific tools can be exchanged quickly and transparently while data flow and process models are completely unaffected BuildDomain New Proxy org openengsb domain build BuildDomain Domain for building projects o Maven Connector Maven connector for the build test and deploy domain New vices Select Instance create new connector instance Now let us return to the web interface After a page refresh we are able to create anew Maven connector instance by following the new link next to the connector description 55 HowTo Integrate services with OpenEngSB Creating new Maven Connector Maven connector for the build test and deploy domain Service Id builder Project path home alex Desktop opener L Maven command clean compile S Validate Service Save setup build connector The service id is an arbitrary name that can be referred to later on i e builder The project path refers to the local copy of the source repository i e home user Desktop openengsb tutorial Finally the maven command is the command line option handed to Apache Maven i e clean build Whenever the connector is ordered to build the project it will now execute mvn clean compile in the project directory of openengsb tutorial Click save to create the connector instance Services J Select Instance AuditingDomain J Example Domain J TestDomain DeployDomain J Bu
49. cess control Access control is done on the service level Core services and connector instances are all published as OSGi services Other services and components always reference these service instances We use the approach of AOP to achieve security of these services The openengsb core security bundle publishes a service that serves as a method interceptor When it is attached to a service every method call on the service is preceded with an authorization check A reference to the method interceptor can be obtained by this line in the spring context xml lt osgi reference id securityInterceptor interface org aopalliance intercept MethodInterceptor gt In order to attach it to an existing bean one has to create a ProxyFactoryBean lt bean id secureServiceManager class org springframework aop framework ProxyFactoryBean gt lt property name proxyInterfaces gt lt value gt other ServiceInterface lt value gt lt property gt lt property name interceptorNames gt lt list gt lt value gt securityInterceptor lt value gt T I lt property gt lt property name target ref lt realBean gt gt lt bean gt When registering a service in code rather than in a spring context xml this can be done as seen in the AbstractServiceManager import org springframework aop framework ProxyFactory UY s80 16 Security in the OpenEngSB ProxyFactory factory new ProxyFactory serviceObj
50. converter step is a class which extends the interface ModelEntryConverterStep A ModelEntryConverterStep interface consists of 4 methods This methods are 2 match functions which define if the given object can be converted by one of the converter methods which are the other 2 functions The interface looks like this public interface ModelEntryConverterStep Checks if the given object is suitable for converting work when getOpenEngSBMoc called e g an OpenEngSBModel wf boolean matchForGetModelEntries Object object Does the converting work for the proxy when getOpenEngSBModelObjects is callec OpenEngSBModelWrapper E Object convertForGetModelEntries Object object Checks if the given object is suitable for converting work when a getter of the 101 How to add new field support for domain models OpenEngSBModelWrapper Uf boolean matchForGetter Object object Does the converting work for the proxy when a getter is called e g OpenEngSBWM OpenEngSBModel E Object convertForGetter Object object The first two functions define the converting functionality if getOpenEngSBModelObjects is called e g we used this to convert a File object to a FileWrapper object The other two functions define the converting functionality if a corresponding getter method is called e g convert FileWrapper object to File object 38 4 2 Add converter step To add the new co
51. ct detection as it is implemented now is a very simple implementation of a conflict checker The checker is based on simple version numbers If the version number of the model which has to be saved doesn t fit to the actual version number the conflict detection throws an error In the future there should be more possibilities for conflict detections been found But for the start this conflict detection is enough Jira ISS UE 82 Chapter 33 Engineering Knowledge Base EKB The EKB as it is now is at the very beginning of its development so there is not much to write here for now The most important thing which is provided by the EKB at the moment is the QueryService 33 1 Motivation The main idea for the introduction of the EKB is the idea to provide automatic transformations of domain models between tools and the OpenEngSB But soon it was clear that this will not the only task the EKB should provide Some other things the EKB shall provide when it is finished will be the QueryInterface service which represents the loading force of models from the EDB this is already implemented the possibility to provide better conflict checkers for the EDB and if possible automatic conflict solving 33 2 Query Interface This service has the task to load models from the EDB Since models are no real objects but proxied interfaces this service has to create a new model instance This new model instance is initialised with the data which
52. d void setStartTime Date startTime Date getStartTime void setEndTime Date endTime Date getEndTime 50 How to define a domain model This model defines a part of a domain model for an appointment domain In this model we also have defined the id of the model with the name id You can see that through the set annotation 23 6 Step 3 Add the model to a domain The last step is to add the model to the specific domain For that you simply have to add the model to the model package in the specific domain Now the model is ready to use in the connectors for the specific domain 23 7 Step 4 Use the model The last step is to use the model For that you have to use a util class which is placed in the core common bundle called ModelUtils An instantiation of a model looks like this Appointment appointment ModelUtils createEmpt yModelObject Appointment class After that you can use the appointment object like a normal instantiated object 51 Chapter 24 HowTo Integrate services with OpenEngSB 24 1 Goal The service integration tutorial shows how to combine and automate different software tools services and applications with OpenEngSB To show OpenEngSB s versatility the use case we will be implementing is a continuous integration CI tool for software development processes The tutorial takes a straight forward approach favoring visible results over architectural details of tool
53. d For a finished example have a look at the class org openengsb core console OpenEngSBInfo Here a short description import org apache felix gogo commands Command import org apache karaf shell console OsgiCommandSupport Command scope openengsb name info description Prints out some information public class OpenEngSBInfo extends OsgiCommandSupport Override protected Object doExecute throws Exception System out println Here is the information return null There is just one single other step which has to be done Go into the core console src main resources OSGI INF bluepring shell config xml and add the following lines lt command bundle xmlns http karaf apache org xmlns shell v1 0 0 gt lt command name openengsb info gt lt action class org openengsb core console OpenEngSBInfo gt OpenEngSBInfo lt command bundle gt 91 HowTo Extend OpenEngSB Console This will lead to following command openengsb info To execute this command start the OpenengSB console in a shell as described above and type in openengsb info this will print out the text Here is the information 92 Chapter 37 HowTo Create a connector for an already existing domain for the OpenEngSB 37 1 Goal This tutorial describes exemplary for all connectors the implementation of an email connector The email connector implements the interface of the which is already implemented in the O
54. e a common collection of import and global declarations These parts are sticked together by the rulemanager to a consistent rulebase So when adding a new rule or function to the rulebase make sure that all imports are present before Otherwise the adding of the elements will fail 10 3 Processes In addition to processing Events in global context specific rules it is also possible to use them to control a predefined workflow The WorkflowService provides methods for starting and controlling workflow processes When the workflow service receives an event it is inserted into the rulebase as a new fact and rules are fired accordingly In addition the event is signaled to every active workflow process Workflow logic may use specific rules to filter these events 18 Chapter 11 Taskbox The Taskbox enables you to combine workflows with Human Interactions 11 1 Core Functionality All workflows started in the OpenEngSB are supplied with the global variable ProcessBag Inside the workflow you can populate the ProcessBag with your data As soon as Human Interaction is needed you have to incorporate the sub workflow humantask which wraps the ProcessBag into a Task You can then query the Taskbox service for open Tasks and manipulate the data inside of the Task Not necessarily by Human Interaction When you are finished you again call the Taskbox service and supply the changed Task The changed data gets extracted and is
55. e artifactId of the OpenEngSB connector archetype e archetypeVersion the current version of the OpenEngSB connector archetype The following parameters have to be defined for the parent of the new connector It is not solely parent of the connector itself but parent of the implementation of the domain and all other connectors of this domain too e parentArtifactld the artifactId of the project parent The following parameters have to be defined for the domain of the new connector e groupld the groupId of the domain e domainArtifactld the artifactId of the domain The following parameters have to be defined for the connector 84 How To Create an Internal Connector e artifactld the connector artifact id Has to be openengsb domains lt yourDomain gt lt yourConnector gt e version the package for the source code of the domain implementation Has to be org openengsb domains lt yourDomain gt e domainInterface The name of the domain interface e parentPackage The package in which the domain interface can be found e package the package for the connector code Usually lt parentPackage gt lt yourConnector gt is used e name the name of the implementation module Has to be OpenEngSB Domains lt yourDomain gt lt yourConnector gt Where lt yourDomain gt has to be replaced by your domain name and lt yourConnector gt has to be replaced by the respective connector name Note th
56. e as the variable The service is searched in the current context and the root context If no service is found the action is stalled for 30 seconds If there is still no service found an Exception is thrown Internally this is handled using proxies When the workflow service is started 12 Context Management all globals are populated with proxies that automatically resolve the service with the corresponding location when a method is invoked Example The auditing service is registered with the interface AuditingDomain The service has property location root with value auditing array with one element The workflow engine contains a global named auditing and a rule that invokes a method on every Event that is processed When the rule fires and the consequence is executed the proxy representing auditing global queries for a service with the location currentContext or the location root containing a location entry auditing Since root services get a service ranking of 1 by default the service current context s would supersede the service located in the root context 13 Chapter 8 Persistence in the OpenEngSB The OpenEngSB contains various different persistence solutions which should be introduced and explained in this chapter 8 1 Core Persistence The OpenEngSB has a central persistence service which can be used by any component within in the OpenEngSB to store data The service is designed for flexibility
57. e externally provided tool 34 1 Prerequisites In case it isn t known what a tool domain is and how it defines the interface for the tool connector then Section 5 4 OpenEngSB Tool Domains is a good starting point If there s already a matching domain for this tool it is strongly recommended to use it If the tool requires a new domain to be created relevant information can be found in Chapter 35 How To Create an Internal Domain 34 2 Creating a new connector project To take burden off the developer of creating the initial boilerplate code and configuration a Maven archetype is provided for creating the initial project structure Furthermore we provide the openengsb maven plugin see or the etc scripts gen connector sh Script which wraps the invocation of the maven plug in which simplifies the creation of a connector project from the archetype It should be used for assisted creation of a new connector project 34 2 1 Using the Maven Archetype It is not recommended to use the maven archetype directly because the genconnector goal of the openengsb maven plugin executes additional tasks I e renaming of the resulting project Furthermore it tries to make sure that the new project is consistent with the naming conventions of the OpenEngSB project The following parameters have to be specified to execute the correct archetype e archetypeGroupld the groupId of the OpenEngSB connector archetype e archetypeArtifactld th
58. e methods updateValidation and createValidation are used to check properties before updateServiceInstance or createServiceInstance are called As the mail service does not want to check properties beforehand it simply returns that all values are OK 37 8 Step 5 Blueprint Setup and Internationalization The Maven archetype already created the blueprint setup for the email service at src main resources OSGI INF blueprint If properties or constructor arguments are needed for the service factory they have to be defined in the blueprint setup here In our case the mail abstraction has to be injected as constructor argument on the creation of the email service factory With regards to internationalization it is necessary to add a name and a description for each property used in the service descriptor see email service factory The properties files for English and German are also already created by the Maven archetype and can be found at src main resources OSGI INF 110n In our case the bundle properties file contains the following entries email name Email Notification email description This is a Email Notification Service username outputMode Username username outputMode description Specifies the username of the email account password outputMode Password password outputMode description Password of the specified user prefix outputMode Prefix prefix outputMode description Subject prefix for all mails sent by this c
59. ect factory addAdvice securityInterceptor OpenEngSBService securedService OpenEngSBService factory getProxy The decision about the allowing the user access to a service as made by looking at the services instanceld Therefore all services that are to be placed under this access control must implement OpenEngSBservice and make sure the instanceld is unique enough to ensure security You may want to derive your service class from AbstractOpenEngSBService The persistence of the security bundle manages a set of GrantedAuthorities Roles for each instanceld There is one exception Users with ROLE_ADMIN are always granted access 9 3 Authentication This chapter describes how to deal with security in internal bundles and client projects For authentication the OpenEngSB provides an AuthenticationProvider as a service It s obtainable via blueprint lt reference interface org springframework security authentication AuthenticationManager gt This service is able to authenticate users org springframework security authentication UsernamePasswordAuthenticationToken and bundles org openengsb core security BundleAuthenticationToken The use of the former is pretty obvious The latter is used for authentication for internal actions that require elevated privilages This authentication should be used with caution and never be exposed externally for security reasons 17 Chapter 10 Workflows The OpenEng
60. ecture of the OpenEngSB This chapter tries to give a short summary of the most important concepts in the OpenEngSB architecture The following graphic shows the architecture of the OpenEngSB In the center we use a bus system to integrate different modules In this case we do not use a classical Enterprise Service Bus ESB but rather the OSGi service infrastructure via Apache Aries Blueprint DM Section 5 1 OpenEngSB Enterprise Service Bus ESB We are using Apache Karaf as the OSGi environment Karaf is used in this case instead of a most basic OSGi environment such as Apache Felix or Eclipse Equinox because it supports us with additional features as extended console support and the feature definitions This base infrastructure including all modifications required for the OpenEngSB is called the Section 5 2 OpenEngSB Infrastructure Within the OpenEngSB Infrastructure so called Section 5 3 OpenEngSB Components and Section 5 4 OpenEngSB Tool Domains are installed Both types are written in a JVM compatible language including OSGi configuration files to run in the OpenEngSB Infrastructure They are explained later within this chapter Different tools running outside the OpenEngSB Infrastructure are called Section 5 5 Client Tools Service Consumer or Section 5 6 Domain Tools Service Provider depending on their usage scenario To integrate and use them within the OpenEngSB so called Section 5 7
61. elopment process it will integrate them Our service bus is used to connect the different tools and design a workflow between them but not to replace them with yet another application For example software engineers like us love their tools and will fight desperately if you try to take them away We like the wheels as they are but we do not like the way they are put together at the moment Chapter 3 When to use the OpenEngSB The OpenEngSB project has several direct purposes which should be explained within this chapter to make clear in which situations the OpenEngSB can be useful for you 3 1 The OpenEngSB as Base Environment OSGi is a very popular integration environment Instead of delivering one big product the products get separated into minor parts and deployed within a general environment The problem with this concept is to get old well known concepts up and running in the new environment In addition tools such as PAX construct allow a better integration into Apache Maven and extended OSGi runtimes such as Karaf allow a richer and easier development Nevertheless setting up such a system for development means a lot of hard manual work Using the OpenEngSB such systems can be setup within minutes 3 2 Reusing integration Components and Workflows The OpenEngSB introduces a new level of ESB Development with all typical ESBs mean to start from the ground and develop a complete own environment only using existing connectors
62. engsb domains lt yourDomain gt e artifactId the artifactId of the project parent Has to be openengsb domains lt yourDomain gt parent e version the version of the domain parent which is usually equal to the current archetype version e name the name of the parent module Has to be OpenEngSB Domains lt yourDomain gt Parent The following parameters have to be defined for the implementation of the new domain e implementationArtifactId the implementation artifact id Has to be openengsb domains lt yourDomain gt implementation 87 How To Create an Internal Domain e package the package for the source code of the domain implementation Has to be org openengsb domains lt yourDomain gt e implementationName the name of the implementation module Has to be OpenEngSB Domains lt yourDomain gt Implementation Where lt yourDomain gt has to be replaced by your domain name which is usually written in lower case i e report for the report domain Note that the archetype will use the artifactId to name the project but the OpenEngSB convention is to use the domain name Therefore you will have to rename the resulting project Do not forget to check that the new domain is included in the modules section of the domains pom 35 2 2 Using mvn openengsb genDomain Simply invoke mvn openengsb genDomain from the domains directory in your OpenEngSB repository alternatively the etc scri
63. es an example for a Gmail account Please use test1 for the Service Id field 33 HowTo First steps with the OpenEngSB Home Test Client Send Event Page Context Services Current Project foo Y logout This is a Email Notification Service Service Id test1 Username example gmail com Password esse Q Prefix TESTMAIL Authentification x Sender Emailadress example gmail com SMTP Port jas S SMTP Host smtp gmail com Validate Service Save 2009 2010 Imprint email notification When you have finished setting all fields to appropriate values create the new instance by clicking the Save button Now create another service with the Service Id test2 Otherwise you can use exactly the same values again You can validate the services open the Services page which should look similar to the following screenshot All your created services should be available with the state ONLINE Home Test Client Send Event Page Context Services Current Project foo Y logout Services with state Connecting Services with state ONLINE Services with state OFFLINE e test1 This is a Email Notification Service Update Service Delete Service e test2 This is a Email Notification Service Update Service Delete Service Services with state Disconnected jo Services available 2009 2010 Imprint overview 18 5 Executing Service Actions Directly Now we re going to validate the created serv
64. gger Service Id example 2 Prefix logging Log Level INFO GL Flush 2 Validate Service Save 2009 2010 Imprint logging service 19 5 Configure Go to the Context page and configure the domains to use the connectors created 37 HowTo Events with the OpenEngSB Using the logging service Home Test Client Send Event Page Context Services Current Project foo Y logout Expand all nodes Collapse all nodes Tree Column value B S domain ExampleDomain S defaultConnector D id example S issueDomain Qj defaultConnector D id issue 2 QjNotificationDomain Gj defaultConnector Did notification path value save 2009 2010 imprint context overview 19 6 Creating a rule On the Send Event Page you can create and edit Rules Therefore they have to be edited directly with a text editor The initial system is empty and does not include any rules To create a rule choose new Enter hellol into the rulename input field Make also sure that Rule is selected in the type dropdown box As soon as you edit the content of the rule you can save your changes by clicking save or revert the changes by clicking cancel The name of the rule will automatically be prefixed with org openengsb Please insert the following content into the text box and save the changes My notification rule Sends Hello World notification to test recipient
65. goingPort interface Also it uses the id property not to be confused with service id defined in the OSGi spec as a unique identification for components that want to interact with remote applications A reference implementation of the OutgoingPort interface is provided in the openengsb core common project lt service representing the outgoing port gt lt service interface org openengsb core api remote OutgoingPort gt lt service properties gt lt entry key id value jms json gt lt service properties gt lt the outgoing port uses a filter chain to manage the entire calling procedure gt lt bean class org openengsb core common OutgoingPortImpl gt lt property name filterChain gt lt bean factory ref outgoingFilterChainFactory factory method create gt lt property gt lt bean gt lt service gt The actual network communication is also implemented in a FilterAction This is an example how a filterchain can be used to handle an outgoing methodCall with a result lt bean id incomingPortBean class org openengsb ports myport MyIncomingPort init method start lt bean id outgoingFilterChainFactory class org openengsb core common remote FilterChainFactory gt lt property name inputType value org openengsb core api remote MethodCallRequest gt lt property name outputType value org openengsb core api remote MethodResultMessage gt lt property name filters g
66. gt h2 lt artifactId gt lt version gt 1 3 163 lt version gt lt dependency gt After you added the dependency you have to make sure the database is loaded before the database connection is established For that just replace following code line in the file assembly src main filtered resources features xml with the new database driver bundle as you can see you only have to copy and paste the values of the dependency 62 HowTo Change EDB database back end lt bundle gt mvn com h2database h2 1 3 163 lt bundle gt After this steps you are done and the EDB uses now the new database as persistence backend 25 4 Use non JPA compatible database If you want to replace the standard database with another non JPA supported database you will have to change first the data source like described in the previous section After that you have to write your own bundle that provides the EngineeringDatabaseService In this case you also have to reproduce all SQL commands and port it for the new database and replace the standard Engineering DatabaseService 25 5 Appendix Use no OSGi compatible database In this case you have to wrap the driver for the database How to do that can be read in the developer manual where wrapping is explained 63 Chapter 26 HowTo Test Remote Messaging using Hermes JMS 26 1 Preparation Those sections shows what have to be done initally 26 1 1 Preparing the Server Before star
67. handed back over to the workflow 11 2 Ul Functionality The Webtaskbox service provides additional UI Features if you want to integrate the Taskbox Concept into a wicket Page You can query the Webtaskbox service for an Overview Panel that displays all open Tasks If the default Overview Panel doesn t fit your needs exactly you can develop your own UI Component using the Core Taskboxservice If you navigate onto a specific Task the Overview Panel displays a default Detail Panel populated with the values of the Task if there is no custom Panel registered for the supplied tasktype You can develop your own Detail Panels and register them for a specific Tasktype via the Webtaskbox service 19 Chapter 12 Remoting The OpenEngSB provides interfaces for interacting with other applications on the network in a generic way that allows using any programming language transport protocol and message marshalling encoding This does not mean that it magically supports all protocols and encodings but rather that it provides a generic API that provides means for integration of new protocols etc All external communication is based on single messages which means the whole mechanism is stateless on its own To realize stateful computations either the filter s or the service must provide such functionality 12 1 Filters Following the Chain of Responsibility Pattern http en wikipedia org wiki Chain of responsibility_pattern the Ope
68. hard as it sounds 29 Chapter 17 HowTo Setup OpenEngSB for development First steps 17 1 Goal This section describes the setup process required for OpenEngSB development If you would like to view a use case centric tutorial take a look at the continuous integration example 17 2 Time to Complete If you are already familiar with Java EE servers about 15 minutes We will not be using advanced concepts so you likely be able to continue with the tutorial even without it 17 3 Prerequisites It is assumed you have basic knowledge of system administration and you are able to set up auxiliary software i e JDK 1 6 yourself 17 4 Java Development Kit 6 First of all the JDK6 should be installed on the system and the JAVA_HOME variable should be set Java download Also make sure that the java command is available in the PATH variable 17 5 Getting OpenEngSB Download the latest OpenEngSB release from here 17 6 Installing OpenEngSB Extract the archive and run the openengsb script bin openengsb bat on windows bin openengsb otherwise Click the following link to open the web interface in your browser http localhost 8090 openengsb You should automatically be directed to a page asking for a login The default login is admin with password as password Username admin Password sseeeeee Login login If everything works fine you should be welcomed by the following page presenting you the c
69. he WebApp see the How to section of the OpenEngSB homepage 100 Chapter 38 How to add new field support for domain models 38 1 Goal This tutorial explains how to create new supported field types for domain models What a domain model is can be read in the user manual in the semantics section Chapter 6 Semantics in the OpenEngSB In this section is also explained which fields are supported until now This task is divided in two subtasks where the second one is optional The first subtask provides the functionality that the model is working correctly with the new field type The second subtask is the possibility that this fields are also saved in the EDB and can be loaded from the EDB 38 2 Time to complete If you are already familiar with the OpenEngSB the first subtask will take about 45 minutes The second subtask will take about another 45 minutes If you are not familiar with the OpenEngSB please read this manual from the start or check the homepage for further information 38 3 Prerequisites For information about how to get started as contributor to the OpenEngSB project and how to get the current OpenEngSB source please read the contributor section of the manual Part V OpenEngSB Contributor Detail Informations 38 4 Subtask 1 Add model support All that have to be done is to add a new converter step to the ModelProxy class in the core common bundle Step by step 38 4 1 Create new converter step A
70. he best way 11 Chapter 7 Context Management The context is one of the most important core concepts of the OpenEngSB It allows to reuse predefined workflows in several contexts A context may often represent a project or subproject So it is possible to execute the same workflow with the project specific tool instances and other metadata like contact information To determine in which context an action should be executed a thread local variable is used The ContextHolder_ keeps track of this variable the current threads context Invoking the set and get method will always manipulate the context of the current Thread When a new Thread is spawned it inherits the context from the parent thread Attention When using Theadpools the ContextHolder may malfunction i e return the context of some previous task that was run in the same thread Use ThreadLocalUtil contextAwareExecutor ExecutorService to convert any executor to a context aware one ExecutorServices returned by this method ensure that the submitted tasks are executed in the same context as the thread they were submitted from This way connector implementations and other client projects always can handle actions according to the current context and execute actions in specific a specific context So when a person with a certain role in the project e g project manager needs to be notified of some event the value of his contact address is specific to the con
71. he dependencies in the wrapped jar 78 Chapter 31 OpenEngSBModels The OpenEngSBModels are the base concept for the whole semantic part of the OpenEngSB They are needed to enable the persisting of domain models into the EDB Also they give the OpenEngSB the possibility to send models via remote and to hide complexity from the user 31 1 Motivation The idea behind the concept of the OpenEngSBModels or domain models is corelated to the domain connector structure of the OpenEngSB Models should represent the objects used by a domain in an abstract manner e g the model Issue in the issue domain Since such models are defined on the domain level All connectors which belong to a specific domain use the models defined by this domain In that way every connector of a specific domain speaks the same language 31 2 Structure of a model What is a little bit different from the normal approach to develop and design such domain models is that in the OpenEngSB all domain models are interfaces This interfaces have to extend the interface OpenEngSBModel which is defined in the core api bundle Which advantage this brings will be explained later on in this chapter Another important thing is the structure of such a model interface Every domain model or OpenEngSBModel interface contains only getter and setter pairs It is important that every getter has a equivalent setter and the other way round to ensure correct behaviour of this m
72. he most complex one If you are not familiar with the OpenEngSB please read this manual from the start or check the homepage for further information 25 3 Use JPA compatible database If you want to replace the standard database with another JPA supported database supported databases listet here the procedure of changing is rather simple You have to change the properties for the database connection of the infrastructure jpa bundle This is done by changing the config file org openengsb infrastructure jpa cfg This file is in the assembly src main filtered resources etc folder The file has the following entries driverClassName here shall be the name of your driver class name example org h2 jdbcx JdbcDataSource url here shall be the url to the used database file example jdbc h2 openengsb username here shall be the username for authentication at the database password here shall be the password for authentication at the database After changing of this file you have to assure that the driver which shall be used by the data source is loaded at runtime For that you have to load the database driver before the connection to the database is established Your database bundle dependency should be added to the parents shared pom xml file A dependency entry for the h2 database looks like this the h2 version is defined as property in the same file lt dependency gt lt groupId gt com h2database lt groupId gt lt artifactId
73. ibute buildAttribute builder smtpPort mail smtp port outputMode mail smtp port outputMode description attribute buildAttribute builder smtpHost mail smtp host outputMode mail smtp host outputMode description build return builder build private AttributeDefinition buildAttribute ServiceDescriptor Builder builder Sicily ie Sring mameto Streit Cesoriprionte i return builder newAttribute id id name namelId description descriptionId defaultValue required build Called by the link AbstractServiceManager when updated service attributes for an instance are available The attributes may only contain changed values and omit previously set attributes param instance the instance to update param attributes the new service settings sdf Override public void updateServicelInstance EmailServiceImpl instance Map lt String SEU aO GicierewWoywiceys 2 setAttributesOnNotifier attributes instance The link AbstractServiceManager calls this method each time a new service instance has to be started param id the unique id this service has been assigned param attributes the initial service settings 2 Override public EmailServiceImpl createServiceInstance String id Map lt String String gt attributes EmailServiceImpl notifier new EmailServiceImpl id mailAbstraction setAttributesOnNotifier attributes notifier return notifier TER Val
74. ices First of all start by open the Test Client link Now open the Notification Domain tree and choose estl Next get the notify method from the drop down box The available fields should change instantly Let the attachment field free and enter anything into 34 HowTo First steps with the OpenEngSB Send mails via the OpenEngSB message and subject The address should be a valid email address not validated for the moment After all the view should look similar to the following image 1d yuman 15 PIUVIUTU ad an CACINpIe TUL an EVEI pE HL STUMM NULUY uSGu NI pIVUUGUUII F o Logging Service Logs messages with a specific log level to the OSGi logger New o Example Domain Proxy service Proxy service to interact with external services New Services 3 5 Select Instance Y 9 BuildDomain Y 7 DeployDomain Y 9 SCM Domain Y 9 Issue Domain 0 TestDomain Y 3 Report Domain QNotification Domain D domain notification org openengsb domain notification NotificationDomain D test1 org openengsb domain notification NotificationDomain Y 9 Example Domain notify org openengsb domain n 1 attachments 2 message fest e recipient example gmail com _ 2 subject fest 9 Call Edit Service 2009 2010 imprint notification properties Call the service by using the Call button Some seconds after you ve pressed the call button the following message should occur on on your screen Methodcal
75. idates if the service is correct before updating RYA Override public MultipleAttributeValidationResult updateValidation EmailServiceImpl instance Map lt String String gt attributes return new MultipleAttributeValidationResultImpl true new HashMap lt String String gt Validates if the attributes are correct before creation ref Override public MultipleAttributeValidationResult createValidation String id Map lt String String gt attributes return new MultipleAttributeValidationResultImpl true new HashMap lt String String gt 98 HowTo Create a connector for an already existing domain for the OpenEngSB The factory is more interesting with respect to the OpenEngSB It is used to create and configure instances of the email service Furthermore it is responsible for publishing which properties a mail notifier needs to be configured in a proper way The getDescriptor method returns a service descriptor which is created with the help of a builder This service descriptor contains the properties a mail notifier needs In this case things like user password smtp server and so on The updateServiceInstance method updates an already created instance of the mail service Basically this means setting the properties which are provided in the attributes map parameter see setAttributesOnNotifier method The createServiceInstance method is responsible for the creation of a new email service Th
76. ife the universe and everything lt action gt lt actionNode gt lt nodes gt lt connections gt lt connection from 3 to 2 gt lt connection from 1 to 3 gt lt connections gt lt process gt After pressing save you can access the process via the message shown above to the receive queue on the OPENENGSB JMS Port which is started by default on Port 6549 Make sure that classes and args has the same number of arguments If you just want an object to be instantiated but have no corresponding values that should be set for the object simply add as in the example above which will instantiate the object but recognize that no values have to be set on the object name SomeName would on the other hand call the setName method with SomeName The response to the above message will be returned on a queue you ve pasted via the callld field 21 1 3 Examples We provide examples in different languages how to connect to the OpenEngSB The examples are grouped according to language and the documentation to the different examples are directly done in the code of the examples We try to keep those examples as good as possible up to date but do not gurantee that they all work as expected since we can t add them to our integration tests If you want to provide examples in different languages you re always welcomed to provide them 47 HowTo Interact with the OPENENGSB Remotely 21 1 3 1 21 1 3 2 21 1
77. ifier getProperties setSender attributes get smtpSender if attributes containsKey smtpHost notifier getProperties setSmtpHost attributes get smtpHost if attributes containsKey smtpPort notifier getProperties setSmtpPort attributes get smtpPort Called when the link ServiceDescriptor for the provided service is needed The code builder already has the id service type and implementation type set to defaults E Override public ServiceDescriptor getDescriptor ServiceDescriptor Builder builder builder name email name description email description builder attribute buildAttribute builder user username outputMode username outputMode description attribute builder newAttribute id password name password outputMode description password outputMode description defaultValue required asPassword build attribute buildAttribute builder prefix prefix outputMode prefix outputMode description attribute builder newAttribute id smtpAuth name mail smtp auth outputMode description mail smtp auth outputMode description defaultValue false asBoolean build attribute buildAttribute builder smtpSender mail smtp sender outputMode 97 HowTo Create a connector for an already existing domain for the OpenEngSB mail smtp sender outputMode description attr
78. ildDomain L domain build org openengsb domain build BuildDom L builder org openengsb domain build BuildDomain Choose One Call o Methodcall called successfully o Result d9adidf1 1036 4f9e bb4a 536ed02b3dd8 test build connector It is time for some action Scroll down all the way in the Test Client tab navigate to the BuildDomain in the tree view and click the builder service From the drop down menu below select build and click the Call button When the project is built successfully a Method called successfully message appears 56 HowTo Integrate services with OpenEngSB alex ubuntu Desktop openengsb tutorial target cla File Edit View Search Terminal Help alexGubuntu Desktop openengsb tutorial target classes gt java org openengsb Main Hello World alexGubuntu Desktop openengsb tutorial target classes l hello world Let us check the directory of openengsb tutorial to find the newly created target directory Using a console we can navigate to the classes sub folder and run java org openengsb Main It returns Hello World Congratulations you have just implemented the core functionality of our CI tool In case an error message is returned we need to check the connector configuration Please make sure that Maven is able to build the project by manually executing mvn clean build in the project directory of openengsb tutorial If this does not work out most likely the setup of ei
79. it is quite simple to configure change and consume and provide configurations it is mostly not a good idea to simply change the properties backend or frontend if you re not exactly sure about what you re doing You can easily take the wrong backend service which will not be able to persist e g a RuleConfiguration and throws exceptions If you swtich the backend during the run everything stored in the old backend would not be available in the new one Within a client project mostly relay on using those services to read the properties and use the OpenEngSB to store them Still the system can easily be extended to your own use Typically you have to do the following steps to provide a new configuration service First of all start by providing an own Configuration which extends ConfigIltem Please only use the metadata and content fields and do not add additional variables They wont get stored Now add a configuration file into etc with org openengsb persistence config ANY_NAME_YOU_LIKE cfg In this file define the region and the backend id The exact values and detailed explanation for those fields is available here If you ve not choosen one of the general available services for storage you now can implement your own backend service registered in the OSGi registry with the ID you ve configured in the cfg file before The interface you have to implement and register as a service is the ConfigPersistenceBackendService 8 2 1 Context configuration per
80. ke an arbitrary id to save the model 80 Chapter 32 Engineering Database EDB The EDB is a core component of the semantic part of the OpenEngSB It s purpose is the persisting and versioning of domain models so called OpenEngSBModel objects 32 1 Motivation The EDB concept was introduced with the idea to build a central persisting unit for the domain models of all domains This central approach offers some interesting advantages like for example e easy to change e easy data maintainence e single point of versioning configuration e central instance where model transformations can take place Model transformation is the out of the scope of the EDB and will be covered by the EKB Another important feature of the EDB are build in conflict checkers Until now there is only one implementation which is based on version numbers Whenever someone tries to save something into the EDB with the wrong version the conflict checker tells the user that a conflict has been found and that he has to checkout the newest version of the model before he can save the model 32 2 Structure The EDB is a JPA based implementation of a central database supplier in service orientated architectures which also have the additional functionality to version data Currently we are using OpenJPA as JPA implementation Since the EDB simulates the functionality of a scm system the structures of the tables in the EDB are no big surprise They consist of
81. l called successfully success Within the next seconds to minutes the address specified by you should receive a mail Next validate if the service test2 does the same Therefore press on test2 choose notify again and enter your values Click Call again and validate if you receive an email 18 6 Executing Service Actions via Domains Till now you ve used the services directly Now one of the OpenEngSB core concepts is presented the Domains To send messages via domains instead of directly via the connectors a default receiver for a specific project has to be set A graphical user interface for doing so is the Context Page 35 HowTo First steps with the OpenEngSB Send mails via the OpenEngSB Home Test Client Send Event Page Context Services Current Project foo Y logout Expand all nodes Collapse all nodes Tree Column value domain 2 ExampleDomain Gj defaultConnector D id example S lssueDomain G defaultConnector D id issue 2 QNotificationDomain Gj defaultConnector Did notification path value save 2009 2010 imprint context Change the entry domains NotificationDomain defaultConnector id to test or test2 Do this by clicking on the node id This should create a drop down box next to it Select test1 or test2 Afterwards go back to the Test Client page and select Notification Domain domains notification Now choose the notify method again and tr
82. lly it is worth mentioning that tools can be integrated with more than one connector This allows one tool to act in many different domains Apache Maven is an example for such multi purpose tools relevant for build as well as test and deploy of Java projects 10 Chapter 6 Semantics in the OpenEngSB One of the core concepts of the OpenEngSB is the correct handling of domain models versionize them and perform model transformations on such models so that they can be easily used by tools which connect to the OpenEngSB 6 1 Domain Models A domain model represents an abstraction of data a domain has to work with e g Issue for issue tracking systems It capsulates all information which is needed for one information unit Such domain models are defined in the domains and can be used by connectors which use the domain This domain models can be saved and versionized with the help of the OpenEngSB and two core components namely the EDB Engineering Database and the EKB Engineering Knowledge base Those two components will be explained in more detail in the contributor manual A domain model is represented as an interface This interface has to extend a provided interface which is called OpenEngSBModel To work with this interface we provide a Utils class ModelUtils which is able to proxy the interface and gives you the feeling like you work with a normal class object Such domain models can be sent via events EDBInsertEvent EDBUpd
83. ly e Which service should be called first e What should be returned as a result All this is specified by a CompositeStrategy Strategy implementations must implement the CompositeConnectorStrategy interface and be registered as OSGi services exporting this interface Also the service must specify the composite strategy name property The strategy is provided with a list of ServiceReferences and the invocation parameters The implementation can decide which services to resolve and to invoke Also the strategy must return a single result 22 2 Create a composite connector A composite connector instance can be created like a regular connector instance You need to supply the following attributes e querystring a string representing an OSGi query All services that match this query are passed on to the strategy as ServiceReferences Example Suppose we have two notification services One has the property location foo notification 1 and the other one has location foo notification 2 A possible query string for the composite service could be location foo notification e composite strategy name The name of the strategy that should be used 49 Chapter 23 How to define a domain model 23 1 Goal This tutorial explains how to define a domain model for a specific domain What a domain model is can be read in the user manual in the semantics section Chapter 6 Semantics in the OpenEngSB The structure of a domain model is
84. m out println Build started This rule matches BuildStartEvent and prints a line to the console window Click save to prepare the rule for testing Switch to the Test client tab select the builder and call the build method If things work out you ll instantly see the Build started notification pop up in the management console It s time to push this further Create another rule i e buildSuccessful and edit it to look like this when Event type BuildSuccessfulEvent then System out println Build successful running tests tester runTests Note as of OpenEngSB 1 1 2 there is a bug in the editor that prevents connector invocations connectorld doSomething from working correctly Search Terminal Tabs alex ubuntu Desktop openengsb 1 1 alex ubu karaf root gt build started Tie build 5 rg L console output The rule also matches BuildSuccessEvent and prints a line to the console window In addition however it calls a method provided by the test connector Remember the runTests method you called in the tester service by using the test client before This has exactly the same effect but replaces manual UI interaction with an automated response Click save and kick off another build using the Test client again There you go Build started and Build successful running tests Congratulations you have created a basic CI tool The foundations have been extended to all
85. n implementing an external connector it is best to test the call you want to receive first via the TestClient so you get the exact message that you will have to work with Please always keep in mind security By default security is turned on If you want to turn it off please take a look into the etc system properties file While using no security for testing is very interesting we would not advise you to send unencrypted messages in a production environment 21 1 2 Calling internal Services To call an internal Service send a methodcall as described before to the receive queue on the server you want to call The service works exactly as defined before There currently are two ways of specifying which service to address e serviceld This will call the service that was exported with the specified id property It behaves like the following Filter in OSGi syntax id lt servicelId gt e serviceFilter This way you can specify any filter in OSGi syntax to adress the service so it is not necessary to bind the client to a specific id but to other properties as well e g location root location lt context gt objectClass wi You can also use both attributes serviceld and serviceFilter It will create a filter matching both constraints Example if you want to execute a workflow via the WorkflowService send 46 HowTo Interact with the OPENENGSB Remotely callId 12345 answer true classes java lang String o
86. n run the following command in the root folder of the OpenEngSB to create an eclipse project for the new connector mvn openengsb eclipse Now import the connector project into Eclipse and implement the email service by implementing the classes EmailServiceImpl java and EmailServiceInstanceFactory java We won t go into detail about the actual mail implementation here so we encapsulated the mailing functionality in a mail abstraction While the class EmailServiceImpl is responsible for the realization of the domain interface the factory is responsible for creating instances of the email service and for publishing the meta data necessary to configure an instance of the email service These two classes are now explained in detail package org openengsb connector email internal import org openengsb connector email internal abstraction MailAbstraction import org openengsb connector email internal abstraction MailProperties import org openengsb core api AliveState import org openengsb domain notification NotificationDomain import org openengsb domain notification model Notification import org osgi framework ServiceRegistration public class EmailServiceImpl implements NotificationDomain private final String id private final MailAbstraction mailAbstraction private ServiceRegistration serviceRegistration private final MailProperties properties 95 return the current state of the service HowTo
87. nEngSB 24 5 Step 1 Source repository alex ubuntu File Edit View Search Terminal Help alex ubuntu mvn version Apache Maven 3 0 2 r1056850 2011 01 09 01 58 10 0100 Java version 1 6 0 20 vendor Sun Microsystems Inc Java home usr lib jvm java 6 openjdk jre Default locale en US platform encoding UTF 8 OS name Linux version 2 6 35 25 generic arch i3 alex ubuntu check maven and JDK version It turns out we actually need a sample project before we can start developing and testing our CI tool In this tutorial we will be using Apache Maven for project and source management and a small Hello World application written in Java For this to work flawlessly we need JDK 1 6 download and Maven 3 download to be set up on the computer 99 alex E Desktop openengsb tutorial r f wd wd src target pom xml tutorial project package You may download and extract the openengsb tutorial download project that works out of the box or set up your own sample project via maven archetypes Put the project files in a memorable location i e home user Desktop openengsb tutorial or C users user desktop openengsb tutorial and that s about it for now 24 6 Step 2 Building the source code gt endg Event rage COMEX gt Dervices 1aSK Uverview Username jadmin Password seeeeeee Login login You could certainly build the project using Maven but we want this to happen from within OpenEngSB
88. nEngSB uses Filters to modularize the processing and transport of incoming and outgoing messages see Figure 12 1 How filters fit in the architecture A filter is responsible for one or more specific transformation steps Ideally a Filter should only represent a specific transformation step to increase reuseability Plain text MethodCall RequestHandler Incoming Port Remote Client Filterchain Plain text Figure 12 1 How filters fit in the architecture A filter is responsible for both ways of a transformation for example a filter that parses a request is also responsible for marshalling the result Since it is a chain of filters every filter has a successor next where it passes it s transformed request After the next filter is done and returns a result the current filter transforms the message to the desired output format This gives filterchains a pyramid like architecture see Figure 12 2 Pyramid like architecture of filters 20 Remoting MethodCall JSON Request String MethodCall Incoming Port ethodR RequestHandler Method Result Message RequestHandler Filter MarshalFilter Figure 12 2 Pyramid like architecture of filters Example Typically an incoming remote call can be divided into the following steps e receive Reads the message in raw form a network stream e unmarshal request transform the raw stream into a Meth
89. ne in the console The target audience of this part are users and in special admins of the system 70 Chapter 27 OpenEngSB console commands This section describes how to control OpenEngSB via the Karaf Console 27 1 Start the console It is not much needed to get the OpenEngSB console started Just type in a shell mvn openengsb provision or execute the corresponding shell script etc scripts run sh 27 2 Available commands This section is work in progress which means that it will be extended every time a new command is available e openengsb info prints out the current project version openengsb domains prints out all available domains 71 Part IV Administration User Interface This part gives an introduction to the OpenEngSB Administration user interface It shows the functionality and gives an idea what the admin can change in the system and how he can perform this changes The target audience of this part are users and in special admins of the system 72 Chapter 28 Testclient The admin interface for the user to manage domains connectors services and things that have things in common with this Also you can test services here If you select a service you can delete it with the corresponding button 28 1 Managing global variables Global variables are needed to access domain services and other helper objects To manage this variables there is a button in the testclient which brings you t
90. ng values if no input is provided the default value is kept Domain Name is domainname notification Domain Interface is NotificationDomain Connector Name email Version is 1 1 0 SNAPSHOT Project Name is OpenEngSB Connector Email Now the maven archetype is executed It asks you to confirm the configuration groupId org openengsb connector artifactId org openengsb connector email version 1 1 0 SNAPSHOT package org openengsb connector email connectorName Email 93 HowTo Create a connector for an already existing domain for the OpenEngSB connectorNameLC email domainArtifactId org openengsb domain notification domainInterface NotificationDomain domainPackage org openengsb domain notification name OpenEngSB Connector Email SHS TE A project named email is created with the following structure email Giee main java EES openengsb pene Ol CaO email internal EmailConnector java EmailConnectorProvider java EmailInstanceFactory java resources OSE R R H A blueprint email notification context xml Iam bundle properties bundle_de properties bundle info pom xml All these artifacts will be covered during the implementation of the connector and explained in step 2 of this tutorial 37 5 Step 2 Add the dependencies Let s start with the dependencies As the email connector
91. nt Tools Service COMSUMET TTT 9 5 6 Domain Tools Service Provider cccccccceccssesceceaeececeaseeceeeaaeseeeeaaeseeeeaaeneeees 9 5 7 Domain and Client Tool Connectors sese eee eee eee 10 6 Semantics in the OpenEngSB sss s sees e sees e ereer 11 6 1 Domain Models ci 2 00 ck ivecee en ii iieii ii iii iania 11 6 2 Load Domain Models sss secrets sectheeecdcceesdedhenetesduenevevdebec sovduceerdedvoners ceeds 11 6 3 Model Transformation escenico rdv regon 11 T Context Management 2 4 seis ici eieen eel eeebesedecedengbeceeseedeseceeds subuesededessogbededeondees 12 Fels Winna SELVICES oirre te Ae ease darn Patek ETER E ENEA EEE E E EE R RERNE 12 Persistence in the OpenEngSB aRar C CER ea 7 EERE EE EER 2 Rs 14 8 1 Core Persistence vre avede susdoca EEEIEE E E EEEE E i R ai 14 8 2 Confio ration Persistence recrea aigein g EE EEA EEEE REEE seeds 14 9 Security im the OpenEn eSB aes ca iren eridi iya NEEE T HARE NE E eaa 75 16 9 1 Usermanagement nionee iire a EEE EELEE E EVE NETE EE 16 9 2 ACCESS CONTON iee Ea shh eel stabs E E E shed ete aie 16 9 3 Authentication nisreen ae a a a E E A a E 17 10 Workflows pii eroi ae ra E aee eed et een Ea ee e a a ae Ea eaaa es 18 10 1 Workflow service tennisni neee eee ee ee i ee 18 10 2 R lemana ger sesos eeoa de A ei oe tae Re E N aS 18 10 3 Processes ustini e a e e E e el ee 18 TL EE a DOK neee adi yeh hall e E oa Sa Ee Satie Oh aes Cad E e A ies 19 Tel Core Te Te 19 T12 O
92. nverter step you have to add the converter step to the list of converter steps in the method initializeModelConverterSteps in the ModelProxyHandler class Important The DefaultConverterStep have to be the last step in the converter step list 38 5 Subtask 2 Add EDB support To accomplish this task you have to extend the EDBConverter class in the EKB bundle WARNING This step is currently under construction and very likely to be changed soon As example for this subtask you can check how it was done with the File object In the EDBConverter there are two functions which have to be extended The first is needed for the conversion of OpenEngSBModels to EDBObjects and the other one is needed for the conversion of EDBObjects to OpenEngSBModels 38 5 1 OpenEngSBModels to EDBObjects For this direction the method convertSubModel has to be extended In the part where every OpenEngSBModelEntry get analyzed a new if statement has to be added which does a special handling if the new introduced wrapper class is the parameter How this wrapper class is saved is up to you 38 5 2 EDBObjects to OpenEngSBModels For this direction you have to extend the method getValueForProperty Again here must also a new if statement been added where the parameter type is checked for the new field object which should be supported If this statement fits you have to undo the conversion which have you done in the OpenEngSBModels to EDBObjects part
93. o a own site where you can manage this variables Here you can add edit and delete them If some error occur while managing the variables deleting a variable that is already in a rule the site tells you what did go wrong 28 2 Managing imports Imports are important so that global variables can work If the class of the global variable isn t imported an error occurs because the necessary classes can t be loaded To manage this imports there is a button in the testclient which brings you to a own site where you can manage this imports Here you can add edit and delete them If some error occur while managing the imports the site tells you what did go wrong 73 Chapter 29 Wiring This user interface constitutes a way for administrators to do wiring Wiring is a process where global variables get connected with connectors domain endpoints in a certain context As there are several steps to do that this page gives you a fast and easy managing possibility For further reading please visit http www openengsb org nightly docbook developer context html 29 1 Wire a global variable with a service 1 Select a domain type in the drop down field Doing that all domain endpoints and all globals of this domain type will be loaded If nothing appears then there will be probably no suitable global available and no suitable connector is instantiated This can be checked on the Testclient page Home Test Client Send Event
94. odCall object e handle the request resolve the corresponding osgi service invoke the method and wrap the result in a MethodResult object e marshal result marshal the result for transporting it over the network e send result send the result back to the caller over the network A port realizing such a transport would consist of a task listening for incoming messages and a chain with two Filters One for marshalling and one handling the request itself An example for such an implementation is the jms json basic port in the openengsb ports jms project The incoming port is represented by a single that listens on a specific jms queue for new requests If a Text message is received it is passed on to the filterchain as a string The filterchain starts with a JsonMethodCallMarshalFilter As the name indicates this filter expects a string containing a json encoded MethodCall The string is transformed into a MethodCallRequest object and passed on to the next filter The next filter is the RequestHandlerFilter It extracts the MethodCall from the request and passes it on to the RequestHandler and wraps the returned MethodResult into a MethodResultMessage The MethodResultMessage is then returned to the JsonMethodCallMarshalFilter There the MethodResultMessage is encoded in JSON and returned to the MessageHandler which then sends it to the answer queue In the JMS Port the result is sent to a queue named after the callId submitted in the Request
95. odels But how to work only with interfaces Since an OpenEngSBModel is only an interface we need a mechanism to work in an efficient way with such objects The way we choose was to create a static model proxy class which simulates the implementation of a model The class enabling this is the ModelUtils class which can be found in the core common bundle Every OpenEngSBModel object has three defined functions getOpenEngSBModelEntries addOpenEngSBModelEntry and deletOpenEngSBModelEntry Whenever getOpenEngSBModelEntries is called the model transform itself into a list of key value pairs where every entry have in addition the type of the value saved This mechanism is used for easier saving of models to the EDB and also to transfer a model to a different machine With the addOpenEngSBModelEntry you can add additional entries which are not part of the model definition itself to the model And finally with the removeOpenEngSBModelEntry you can manually remove an entry which has been inserted manually through addOpenEngSBModelEntry 31 3 Supported field types Currently the models are able to work with primitive types strings dates lists maps models and files All those objects can be set and got through the interface and can also be persisted in the EDB see the chapter about the EDB for more details Special case in the supported field types are file objects They are quite tricky especially if the models shall be transfered to another
96. onnector mail smtp auth outputMode Authentification mail smtp auth outputMode description Specifies if the smtp authentication is on or off mail smtp sender outputMode Sender Emailadress mail smtp sender outputMode description Specifies the Emailadress of the sender mail smtp port outputMode SMTP Port mail smtp port outputMode description Specifies the Port for the smtp connection mail smtp host outputMode SMTP Host mail smtp host outputMode description Specifies the SMTP Hostname 99 HowTo Create a connector for an already existing domain for the OpenEngSB As you can see each property is defined with name and description The same entries can be found in the German properties file bundle_de properties with German names and descriptions 37 9 Step 6 Start the OpenEngSB with your Connector After implementing and testing your connector locally you can try to start up the OpenEngSB with your new connector Enter the following commands in the root directory of the OpenEngSB to build and start the OpenEngSB in development mode mvn clean install mvn openengsb provision Now you can enter list into the karaf console to check whether your new connector was installed and started 37 10 Step 7 Test the new connector Now you can use the OpenEngSB administration WebApp available at http localhost 8090 openengsb to test your new connector For more information about how to use t
97. or certain implementations The proxy calls the CallRouter which redirects the methodcall to the respective Port Security is implemented in this layer 25 Chapter 14 Deployer services The OpenEngSB supports file based configuration through its deployer services These services are constantly checking the config directory for new changed deleted configuration files If a new file is created its configuration is loaded into the OpenEngSB When the file changes the configuration is updated and when it is deleted the configuration is unloaded Each deployer handles a different type of configuration file represented by different file name extensions Details and structure of these files are covered in this section It should be noted that the OpenEngSB itself uses deployer services for internal configuration For this purpose the deployer services also listen for configuration files in etc These config files however are essential for the correct operation of the OpenEngSB and should not be modified 14 1 Connector configuration The connector deployer service creates updates or deletes instances of connector services All files in the config directory with the extension connector are handled by the connector deployer The connector files have to be simple property files containing the configuration properies of a certain connector service and their values Those files have to follow a specific form to be read correctly
98. ork Common Version 169 Active Created 60 OpenEngSB Framework Services Version 170 Active Created 60 OpenEngSB Framework Persistence Layer Version In order to install domains and connectors from other repositories you need to add the corresponding feature URLs Note that in order to install a connector you need to install all domains it implements In order to install a domain first add the feature repository using the command features addurl When the URL has been added the domain can usually be installed using features install root openengsb gt features addurl mvn org openengsb domain org openengsb domain notification domain vers root openengsb gt features install openengsb domain notification Note that domains and connectors are versioned independently of each other and the OpenEngSB 31 HowTo Setup OpenEngSB for development First steps 17 8 First Steps Now that the OpenEngSB is up and running and all required bundles are installed start with the first integration tutorial 17 9 Shutdown OpenEngSB To shutdown the OpenEngSB go to the command window and type shutdown or press Ctrl D 32 Chapter 18 HowTo First steps with the OpenEngSB Send mails via the OpenEngSB 18 1 Goal This section describes a hello world use case for the notification domain using the email connector 18 2 Time to Complete If you are already familiar with setting up services in Open
99. ow for easy auditing and extensibility Of course at the moment it simply replicates the functionality of existing CI tools but it can be easily extended using SCM access reporting and notification tools and work together with project management software and PIM applications Take a look on the long list of available domains and tool connectors If you want to do some more practice you can add more rules i e for TestSuccessEvent or BuildFailureEvent You can find event types names and properties by checking the event log displayed on the Send Event page 60 HowTo Integrate services with OpenEngSB 24 9 Further Reading There are a number of different HowTo s and tutorials in the online documentation They describe different scenarios for setup connectors and domains and event processing Also the user manual contains additional information about the topics discussed and numerous OpenEngSB sub projects i e OQpenCIT and OpenTicket can be used for reference 61 Chapter 25 HowTo Change EDB database back end 25 1 Goal This tutorial describes how to change the database which is used by the EDB to persist OpenEngSBModels 25 2 Time to Complete The time needed to perform this task depends heavily on which database you want to use instead of the standard H2 database and on your experience with the OpenEngSB This chapter will list the different possibilities from the shortest time period needed to t
100. penEngSB Therefore this tutorial describes the implementation of a connector for an already present domain 37 2 Time to Complete If you are already familiar with the OpenEngSB about 30 minutes If you are not familiar with the OpenEngSB please read this manual from the start or check the homepage for further information 37 3 Prerequisites Warning This section is likely to change in the near future as domains and connectors are currently separated from the rest of the OpenEngSB project Currently connectors are developed together with the core system For information about how to get started as contributor to the OpenEngSB project and how to get the current OpenEngSB source please read the contributor section of the manual Part V OpenEngSB Contributor Detail Informations 37 4 Step 1 Use the archetype As the development of a connector is a recurring task the OpenEngSB developer team has prepared Maven archetypes and useful mojos which provide support for the initial creation of a connector A new connector can be created by invoking mvn openengsb genConnector or using etc scripts gen connector sh Go into the directory connector and invoke the mojo from there It generates the result in the directory from where it is started therefore it is recommended to run it from the connector directory You can also run it from a different directory and copy the results into the connector directory Fill in the followi
101. plement Operations that connectors should provide are specified here Events that are raised by this Domain in unexpected fashion e g new commit in scm system are specified on the Interface The Raise Annotation and the array of Event classes it takes as an argument are used If the Raise annotation is put on a method the events that are specified through the annotation are raised in sequence upon a call 2 Domain event interface This is the interface the domain provides for its connectors to send events into OpenEngSB The event interface contains a raiseEvent SomeEvent event method for each supported event type 3 Domain Provider The domain provider is a service that provides information about the domain itself It is used to determine which domains are currently registered in the environment There is an abstract class that takes over most of the setup 4 Blueprint context There are three services that must be registered with the OSGi service environment First there is the Domain Provider Moreover the domain must provide a kind of connector itself since it must be able to handle service calls and redirect it to the default connector specified in the current context And finally the domain provides an event interface for its connectors which can be used by them to send events into OpenEngSB The default implementation 89 How To Create an Internal Domain of this event interface simply forwards all events sent
102. pts gen domain sh script can be used which invokes the openengsb maven plugin for you domains mvn openengsb genDomain You ll be asked to fill in a few variables which are needed to create the initial project structure Based on your input the mojo tries to guess further values Guessed values are displayed in brackets If the guess is correct simply acknowledge with Return As example the following output has been recorded while creating the Test domain Domain Name mydomain test lt Enter gt Version 1 0 0 SNAPSHOT lt Enter gt Prefix for project names OpenEngSB Domains Test lt Enter gt Only the domain name has been filled in while the rest has been correctly guessed After giving the inputs the Maven archetype gets executed and may ask for further inputs You can simply hit Return as the values have been already correctly set If the mojo finishes successfully two new Maven projects the domain parent and domain implementation project have been created and setup with a sample implementation for a domain 35 2 3 Project structure The newly created domain should have the exact same structure as the following listing See igual jay java gt OE openengsb domain mydomain MyDomain Domain java MyDomain DomainEvents java MyDomain DomainProvider java 88 How To Create an Internal Domain resources OSGi INT blueprint
103. rect versions into the dependencyManagement section You can now define the dependencies shared between your project and OPENENGSB in your dependencies section without setting the version 28 Chapter 16 OpenEngSB Platform The aim of the OpenEngSB project as for every open source project is to make the life of everyone better Or at least the life of engineers With that said we want to support projects using the OpenEngSB as base environment or providing domains and connectors While it is easy to find a source repository and use the OpenEngSB because of its business friendly Apache 2 license it is not that easy to get the visibility your project earns We want to provide you with this visibility by including your project into the OpenEngSB product family Basically we provide you with the following infrastructure e Sub domain within the OpenEngSB yourproject openengsb org e Upload space for a homepage at yourproject openengsb org e Two mailinglists yourproject dev openengsb org and yourproject user openengsb org e A git repository at github com openengsb yourpoject e A place at our issue tracker e A place at our build server To get your project on the infrastructure you have to use the Apache 2 license for your code and use the OpenEngSB It is not required to have any existing source base Simply send your project proposal to the openengsb dev mailing list and we ll discuss your project Don t be afraid it s not as
104. rg openengsb core api workflow model ProcessBag methodName executeWorkflow metaData servicelId workflowService contextId foo args simpleFlow Please be aware that the flow the above method tries to call simpleFlow is not available by default on the OpenEngSB To make sure that there s a flow you can call install the flow in the OpenEngSB Therefore start the OpenEngSB and go to the SendEventPage There choose to create a new process and press new Now enter simpleFlow as processname and past the following process lt process xs schemaLocation http drools org drools 5 0 process drools processes 5 0 xsd type RuleFlow name simpleFlow id simpleFlow package name org openengsb xmlns http drools org drools 5 0 process xmlns xs http www w3 org 2001 XMLSchema instance gt lt header gt lt variables gt lt variable name processBag gt lt type name org drools process core datatype impl type ObjectDataType className org openengsb core api workflow model ProcessBag gt lt variable gt lt variables gt lt header gt lt nodes gt lt start id 1 name Start x 16 y 16 width 91 height 48 gt lt end id 2 name End x 21 y 168 width 80 height 40 gt lt actionNode id 3 name Action x 21 y 96 width 80 height 40 gt lt action type expression dialect mvel gt processBag addProperty test 42 processBag addProperty alternativeName The answer to l
105. rkflows and similar important ideas Furthermore this part covers installation configuration and usage of the administration interface to implement a tool environment according to your needs The target audience of this part are developers and contributors Chapter 4 Quickstart As a developer you have basically two ways in which you can use the OpenEngSB One option is to use the OpenEngSB as a runtime environment for any project In addition you ve the possibility to write Plug Ins Domains Connectors for the OpenEngSB Both cases are explained in this chapter 4 1 Writing new projects using the OpenEngSB TBW Jira ISSUE 4 2 Writing Domains for the OpenEngSB To create a new Domain run mvn openengsb genDomain or use etc scripts gen domain sh in the domain folder You will be asked for the name of your domain Enter the domain name starting with a lower case letter For the other questions valid defaults are given The new domain project will be added as a submodule You eventually want to run mvn openengsb eclipse and import the new project in eclipse Add the methods your domain supplies to the domain interface If your domain raises any events add methods like void raiseEvent YourEvent event your event class subtype of Event as single parameter to the events interface 4 3 Writing Connectors for the OpenEngSB To create a new Connector run mvn openengsb genConnector or use etc scripts gen
106. roperty name inputType value java lang String gt lt property name outputType value Jjava lang String gt ler ies Vier hal ees eae lt property name filters gt lt list gt lt A class implementing the FilterChainElement interface gt lt value gt org openengsb core common remote JsonMethodCallMarshalFilter lt value gt ai instante of 4 filter factory gt lt bean class org openengsb ports myport MyFilterFactory gt lt propety name foo value bar gt lt bean gt lt The last item in the list may be an instance of a FilterAction gt lt bean class org openengsb core common remote RequestMapperFilter gt lt property name requestHandler ref requestHandler gt lt bean gt ay las lt property gt lt bean gt When configuring the filter chain you have to make sure that each filter in the list is compatible with its predecessor Compatibility is checked when the create method is invoked In the above example this would be while processing the blueprint file 12 3 Develop custom filters The filters provided by the OpenEngSB only cover the the requirements for the ports that are provided by the OpenEngSB itself For custom ports custom filter classes may be required Filterclasses that are to be used at the end of a chain must implement the FilterAction interface In order to be usable anywhere in the filterchain the Classes must implement the FilterChainElement interface
107. rroaren airna ia a E a a aa desde R S Ni 32 17 9 Shutdown OpenFngSB eres ieoi tiite na e a aa a ie 32 18 HowTo First steps with the OpenEngSB Send mails via the OpenEngSB 33 Ie RE E T EEEE EE EEEE ETEA 33 18 2 Time to Complete ssis iristen aa aaea a eaa e e aaa a ea aAA 33 18 3 Prerequisite Sk eon aeternitate teig ien E E a AE E a E EE E EEE ERS 33 1 4 Creating E Mail Services i coishiveiscedivedorstaietetibaeeoisbivetoeaadel SEEE E 33 18 5 Executing Service Actions Directly eee 34 18 6 Executing Service Actions via Domains sese eee eee 35 18 7 Next Steps ivcieicu 255 etoile sien ee oi Se I ee eee ees SL seed 36 19 HowTo Events with the OpenEngSB Using the logging service sese ee eee 37 19D eT isso cee oes be eee ob eh section E EE ality oe Ne E ae 37 19 2 Time to Complete iscsi ncciee oe oe a leet i ele eee 37 1923 R LUE i xocsisve sais usecase sores AE ees Sunes EEEN RRE E ERRE E 37 19 4 Create required CONNECIOLS TT 37 19 5 Conf Sure 4 5 5 fedora seuss N E EEEE wees ids Wedel esi 37 19 6 Creating 1 oegi an second deeds Avedecstendoces E E bei dees TAE aencgees an ceased dees 38 19575 Throw Event av aGis ua carted wees ean eae DA 39 19 8 NeXt SLEDS annn aee o haedels iu oses av geste eae EAE E Aeeeeg bes oh E 40 20 HowTo Create a Client Project for the OpenEngSB sese eee ee eee 41 QOD CGAL TTT 41 20 2 Tim to Complete essnee enre nti ien a ae ek ee we eh eae 41 20 3 Step t Needed
108. s They are used as regular jar files in the OpenEngSB Nevertheless the wrapping itself is not as painless This chapter tries to explain the process in detail 30 1 Create Wrapped Artifacts This chapter is a step by step guide on how to create a wrapped JAR 1 In case that no OSGi compatible library is available in the public repositories a package has to be created Because of the simplicity of the process it should be done by hand First of all create a folder with the name of the project you like to wrap within openengsb wrapped Typically the groupld of the bundle to wrap is sufficient For example for a project wrapping all Wicket bundles the folder org apache wicket is created 2 As a next step add the newly created folder as a module to the openengsb wrapped pom xml file in the module section For the formerly created Wicket project org apache wicket should be added to the module section 3 Now create a pom xml file in the newly created project folder 4 The pom xml contains the basic project information As parent for the project the wrapped pom xml should be used Basically for every wrapped jar the project has the following structure lt xml version 1 0 encoding UTF 8 gt Sloe OPENENGSB LICENSE gt lt project gt lt parent gt lt groupIid gt org openengsb wrapped lt grouplid gt lt artifactId gt openengsb wrapped parent lt artifactId gt lt version gt 6 lt version gt lt parent gt lt
109. s on the layer of generic domains instead of specific tool properties This provides an out of the box solution which allows typical engineering teams to optimize their processes and make their workflows very flexible and easy to change Also OpenEngSB simplifies the replacement of individual tools and allows interdepartmental tool integration Project management is set to a new level since its possible to clearly guard all integrated tools and workflows This offers new ways in notifying managers at the right moment and furthermore allows a very general distanced and objective view on a project Although this concept is very powerful it cannot solve every problem The OpenEngSB is not designed as a general graphical layer over an Enterprise Service Bus ESB which allows you to design ALL of your processes out of the box As long as you work in the designed domains of the OpenEngSB you have a lot of graphical support and other tools available making your work extremely easy But when leaving the common engineering domains you also leave the core scope of the service bus OpenEngSB still allows you to connect your own integration projects use services and react on events but you have to keep in mind that you re working outside the OpenEngSB and falling back to classical Enterprise Application Integration EAI patterns and tools However this project does not try to reinvent the wheel OpenEngSB will not replace the tools already used for your dev
110. setup a client project for OpenEngSB using maven archetype 20 2 Time to Complete If you are already familiar with the OpenEngSB about 30 minutes This includes only the setup for the project If you are not familiar with the OpenEngSB please read this manual from the start or check the homepage for further information 20 3 Step 1 Needed tools You need to have following tools to be installed 20 3 1 Java Development Kit 6 First of all the JDK6 should be installed on the system and the JAVA_HOME variable should be set Java download Also make sure that the java command is available in the PATH variable 20 3 2 Maven 3 You will also need Maven 3 be installed on your system Maven download Also make sure that the maven command is available in the PATH variable 20 4 Step 2 Using the archetype The OpenEngSB provides an maven archetype to create a client project To use it go into your target directory and type in a shell mvn openengsb genClientProjectRoot The script generates the result in the directory from where it was started You will be asked to fill out following values if no input is provided the default value is kept Project Group Id org openengsb client project Project Artifact Id openengsb client project Project Name Client Poject Project Version 1 0 0 SNAPSHOT Project Description This is a client project for the OpenEngSB Project Url http www openenbsb org OpenEngSB version 1
111. shaller Therefore create a class with a default constructor extending CustomJsonMarshaller Then annotate the parameter of the implementations you re using with the UseCustomJasonMarshaller annotation adding the Marshaller class That s it The framework will automatically create the mapper and call the transform method for you Since there is an issue right now with Aries Proxies hiding parameter annotations the CustomMarshallerRealTypeAccess interface provides a workaround for the problem In case this interface is found the class provided by it is used for searching Otherwise the class directly is scanned 48 Chapter 22 HowTo Combine multiple connectors It is possible to combine several connector instances to one parent connector that appears to workflows like any other connector For example you may want to have several notification connectors in a workflow It uses the location placeholder foo So when the workflow expects the connector instance at location foo you may want it to call multiple connectors One would expect that simply assigning the location foo to every connector would create this behaviour but it doesn t By default the connector with the highest service ranking is chosen see OSGi core specification section 5 5 5 22 1 Composite strategies There are also other issues with using multiple service in a place where one single service is expected e Should the services be called concurrently or sequential
112. sistence The context configuration persistence follows the basic configuration persistence scheme In this case the backend ContextFilePersistenceService creates files for each context basically empty files with filename lt contextId gt context the context service ContexServiceImpl requests a config persistence service of type CONTEXT is given the aforementioned one and uses it to persist its data 15 Chapter 9 Security in the OpenEngSB 9 1 Usermanagement The OpenEngSB has a central user management service which can be used for example by an user interface The service is designed to manage your users You can create new user and save them to the persistence or retrieve update and delete them The user management needs a back end database e g the central persistence service of the OpenEngSB The interface of the User manager supports basic CRUD mechanisms create retrieve update delete The User is the used user model It holds attributes like a password username if the user is enabled or his account is expired or locked A user is identified by his username So the username can not be changed Another attribute are the authorities These are the roles granted to the user These can be for example ROLE_ADMIN which defines the user as admin Depending on the roles a user can have different rights For the OpenEngSB UI a user has to have at least the role ROLE_USER which is the default role 9 2 Ac
113. strings flows as xml files and connectors as key value pairs Being so specific the 14 Persistence in the OpenEngSB implementations of the backends also have to be specific Besides there are kind of regions Examples are Rules Flows and various others Basically in you code you simply want to ask for a configuration persister for rules and do not care if it is a file persister or something else In addition rules could be persisted somewhere else than e g flows Therefore those backends have to be configured separate for each type Ok after the need is identified let s take a look at the how Basically it s quite simple You register various backend services in the OSGi registry give them a specific ID configure how a region is mapped to an idea and request a persister for a specific region or type and retrieve the correct implementation From a user point of view this system is quite simple Use the getConfigPersistenceService String type method from the OpenEngSBCoreServices class with the type which is typically stored directly at the configurations as for example for the RuleConfiguration and retrieve and persist RuleConfigurations The mapping between the backend and the frontend is defined in the configuration file here If you want to use another available and compatible backend for rule configurations add the backend id in the configuration file and the service for this region will switch automatically Although
114. sword Password data L value yourpassword U binaryData L message methodCall classes org openengsb core api Event methodName audit args H name abc U realClassImplementation org openengsb core api Event Configure a message for the OpenEngSB e Press Send to send your message there is no further response or notification that the message was sent Press Done to close the window e Now Doubleclick on the queue with your callId you should see your responses IMSPriority IMSCorrelationID IMSExpiration IMSType IMSReplyTo JIMSTimestamp ID Hugo 1598 13246 random aid Cc 1 ID Hugo 1598 13246 randomCallld Fri Dec 23 19 00 35 C nessage result type Void className null arg null metaData contextId foo serviceld audi ting memoryauditingtauditing root callI da randomCallId timestamp 1324663235031 Retrieve a message response e If you do not see a respone then enter display in the console of your OpenEngSb server to view the last logmessages It is likely that you will see some Error messages concerning your Jsonmessage there Have fun testing with Json 69 Part Ill Administration Console This part gives an introduction to the OpenEngSB Console It shows the functionality and gives an idea what the admin can change in the system and how this is do
115. t 23 Remoting Se lt value gt org openengsb core common remote JsonOutgoingMethodCallMarshalFilter lt value gt lt bean class org openengsb ports jms JMSOutgoingPortFilter gt lt property name factory gt lt bean class org openengsb ports jms JMSTemplateFactoryImpl gt lt property gt lt bean gt IE lt property gt lt bean gt 24 Chapter 13 External Domains and Connectors Since tools are mostly neither developed for the OpenEngSB nor written in any way that they can be directly deployed in the OpenEngSB environment a way is required to connect via different programming languages than Java and from multiple protocols 13 1 Proxying The proxy mechanism allows for any method call to be intercepted 13 1 1 Proxying internal Connector calls The proxy mechanism allows to create proxies for any domain To create a proxy you have to provide a port id destination and service id to call on the remote service A Port encapsulates the protocol that is used to call another service There are an OutgoingPort and IncomingPort interface for respective purposes The port id is used to load the Port via OSGi To include a Port in OPENENGSSB it just has to be exported via OSGi The destination is a string that has to be correctly interpreted by the port to call the remote server The service id is added as metadata do identify the service that should get called on the remote server It may not be needed f
116. table 1 1 2 RELEASE The latest stable release of OpenEngSB is 1 1 2 RELEASE OpenEngss stable multiplatform mr s Download OpenEngsB 1 1 2 RELEASE source zip c tar download openengsb Getting OpenEngSB is simple Go to openengsb org download the latest stable version to your computer and unpack the archive to a convenient location Before you fire up OpenEngSB for the first time please make sure you have a Java Development Kit 1 6 available and set up alex ubuntu Desktop openengsb 1 1 2 RELEASE bin File Edit View Search Terminal Help alex ubuntu Desktop openengsb 1 1 2 RELEASE bin openengst openengsb console You can startup OpenEngSB via the openengsb script in the bin folder If you want to explore the web interface yourself before digging into implementing the CI use case open up your web browser and navigate to http localhost 8090 openengsb and log on as admin with password password Mozilla Firefox marks Tools Help a K http localhost 8090 openengsb etting Started WLatest Headlines ye OpenEm openengsb web UI If you want to take a break or shutdown OpenEngSB in the middle of the tutorial go ahead and do not worry All changes made so far are saved and restored upon restart so you can continue working with the most up to date state Use the shutdown command in OpenEngSB s management console to stop any running services 53 HowTo Integrate services with Ope
117. text of the project s he is managing 7 1 Wiring services The context is also used to handle the wiring of services in workflows Suppose there are two projects that use their own SCM repositories and for both repositories connector instances were created to poll them When executing a workflow contains an action that polls the SCM the correct service ca be picked by looking up the current thread s context In general workflows have references to several domains and other services which they interact with during execution Each project might have their own tools behind these domains so these references must be resolved at runtime depending on the current context For this to work the workflow engine declares global variables that are used in rules and processes A variable is resolved by looking up the service with the same name in the current context If no service with that name is available in the context it is looked up in the root context In detail the wiring is handled via the service properties Services contain properties where the key is of the format location lt contextid gt The value is a list of locations represented by an array of strings So a service may have several locations in several contexts When a global variable is accessed during the execution of an action from a process or rule the OSGi context is queried for the corresponding service The service wired to this variable must have location with the same nam
118. ther Maven or JDK are incorrect If it works however please check the configuration of the connector by navigating to the builder service in the web interface again and clicking the Edit Service button 24 7 Step 3 Testing binaries The next step in building the CI tool is implementation of automated testing We can use the test domain to achieve this Conveniently the Maven connector also exports this type of functionality and we do not to load any additional features in the management console Creating new Maven Connector Maven connector for the build test and deploy domain Service Id tester Project path home alex Desktop opener Maven command test S Validate Service Save setup test connector instance Use the Test client tab and create a new instance of the Maven connector for the test domain It works the same way as before The Service Id is an arbitrary name i e tester The project path points at the location of openengsb tutorial s base directory i e home user Desktop openengsb tutorial and the maven command indicates the command line arguments passed to Maven i e test Click save to create the connector instance 57 HowTo Integrate services with OpenEngSB Services 3 Select Instance T L AuditingDomain T Example Domain J TestDomain L domain test org openengsb domain test TestDon L tester org openengsb domain test TestDomain T J DeployDomain O BuildDomain
119. through the domain to the workflow service However domains can also provide their own implementation of their event interface and add data to events or perform other tasks There is a bean factory that creates a Java Proxy that can be used as ForwardService both for the forwarding of service calls from domain to connector and for the forwarding of events to the workflow service The service call to ForwardService looks up the default connector for the specified domain in the current context and forwards the method call right to it The event forward service simply forwards all events to the workflow service of OpenEngSB 35 4 Connectors For information regarding the implementation of connectors for the newly created domain see Chapter 34 How To Create an Internal Connector 90 Chapter 36 HowTo Extend OpenEngSB Console 36 1 Goal This tutorial shows how to extend the OpenEngSB console 36 2 Time to Complete To read this tutorial and get add a first command should not take more than 10 minutes 36 3 Prerequisites This HowTo assumes you already have downloaded the OpenEngSB 36 4 Start the console It is not much needed to get the OpenEngSB console started Just type in a shell mvn openengsb provision or execute the corresponding shell script etc scripts run sh 36 5 Adding new commands This section describes how to add new commands The project is located in core console To add a new command not much is neede
120. ting the server you have to edit the file OPENENGSB_HOME etc system properties You will find the lines Uncomment to disable encryption for jms messages org openengsb jms noencrypt true Uncomment to disable signature and timestamp verification for all remote requests org openengsb security noverify true Uncomment or if not existing add the lines org openengsb jms noencrypt true org openengsb security noverify true This will enable you to send unencrypted messages to the server Now start the server and enter the following line features install openengsb ports jms This will open the JMS port of the OpenEngSb server which is used to receive Json messages Resolved L act ivemq blueprint 5 5 1 Active L l Apache ServiceMix Bundles jasypt lt 1 6 0 1 gt Active Created activemq core 5 5 1 Active Active kahadb 5 5 1 activemq console 5 5 1 L L Active L activemg ra 5 5 1 L L Active activemgq pool 5 5 1 Active Created activemg karaf 5 5 1 Active L Apache ServiceMix Specs Scripting API 1 0 3 H gt H Active Created Apache XBean OSGI Blueprint Namespace Handler 3 7 Active Created OpenEngSB Infrastructure JMS 3 6 8 SNAPSHOT gt Active Created OpenEngSB Ports JMS 3 6 8 SNAPSHOT gt Installation Check 26 1 2 Setup Hermes e Download the latest Hermes version from www hermesjms com e Download ActiveMQ from activemq apache org e Unpack ActiveMQ e Inst
121. tion of the OpenEngSB builds on serialisation it can happen that some additional actions are required to restore the object In that case make use of the SpecialActionsAfterSerialisation interface If your entities implement the interface the doSpecialActions method is called after restoring allowing you to do additional actions to the bean before it s returned to the caller The persistence solution of the OpenEngSB was designed to support different possible back end database systems So if a project has high performance or security requirements which can not be fulfilled with the default database system used by the persistence service it is possible to implement a different persistence back end To make this exchange easier a test for the expected behavior of the persistence service is provided 8 2 Configuration Persistence Besides the centralized Java Bean store the OpenEngSB also have a more specialized solution to store configurations Configurations are basically also Java Beans but have to extend a ConfigItem Well since Configurations are also only Java Beans you may ask Why not simply store them via the persistence service The reason is quite simple We do need to store configurations at various places Options may be the file system an object store or any other place In addition configurations when you e g store them to files have to be quite specific about their types Rule for example have to be stored as simple
122. ts 74 Wiring 5 After submitting the form a success message for each context should appear If an error occurs an error message will be shown wire o No update was done at context foo2 because auditing already wired in that context o Wiring was successfully done for auditing at context foo Screenshot of the wiring results 29 2 What wiring does in the background The properties of the service will be updated First it will try to get the property with the key location context from these properties because there are all locations stored If there is no such property a new one will be added After that it will insert a new location in that property which is the name of the given global As there can be more locations the new one will be appended excepted such location already exists Then nothing will be changed but an info message will appear 75 Part V OpenEngSB Contributor Detail Informations This part gives an introduction to more detailed concepts of the OpenEngSB which should be interesting for contributors which should have a deeper view on specialised topics of this project This part is also interesting for users which want to have a deeper insight what is happening in the background of the OpenEngSB magic 76 Chapter 30 Prepare and use Non OSGi Artifacts Basically wrapped JARs do not differ in any way from basic jars besides that they are deployable in OSGi environment
123. urrently installed domains 30 HowTo Setup OpenEngSB for development First steps Home Test Client Send Event Page Context Services Current Project foo Y logout This page represents the OpenEngSB management interface Via this interface the core systems of the OpenEngSB such as workflows rules domains and connectors can be configured and tested This interface fulfills a similar purpose as administration interfaces in classical application servers as Apache Tomcat 2009 2010 Imprint main page 17 7 Setup required domains OpenEngSB implements it s functionality in so called features Each feature contains a number of OSGi bundles While all features are distributed with the OpenEngSB not all of them are installed to speed up the startup For the next section First Steps it is required to install additional features Therefore open the console in which you ve started the OpenEngSB and enter list which should output something like karaf oroot list SLART LEVEL OOE eUl Tp ID State Blueprint Level Name 42 Active Created 60 Apache Karaf Shell Service Wrapper 2 2 116 Active 60 Jackson JSON processor 1 5 3 L65 Active Created 60 OpenEngSB Framework API Version L66 Active Created 60 OpenEngSB Framework Engineering Database Version 167 Active Created 60 OpenEngSB Framework Engineering Knowledge Base Vers 168 Active Created 60 OpenEngSB Framew
124. using the default log connector of the log domain to write information to a log file Notification uses the default notification connector to inform a person More details about this topic can be found in the user documentation at rules domains and connectors To run a test the n setRecipient property should be changed to a e g your email address 19 7 Throw Event Now we can throw an event and see if the rules work correctly Stay on the Send Event Page enter for the contextld field foo and press send foo represents the name of the project For a detailed description about projects and the context see the user documentation You ve should received a email via the rule to the email address configured previously In addition using the log display command in the OpenEngSB console should present anywhere in the long log a logging entry similar to the following you have to search for the output of the LogService The other fields can change 3 INFO btpool 39 HowTo Events with the OpenEngSB Using the logging service 19 8 Next Steps Congratulation You ve gained basic knowledge about the OpenEngSB and its functionality Nevertheless you ve just touched the surface As a next step it is recommended continue with further tutorials user manual and start exploring the world of the OpenEngSB 40 Chapter 20 HowTo Create a Client Project for the OpenEngSB 20 1 Goal This tutorial describes how to
125. va e ia errr enne E E E EE T be E E EE eie 83 33 2 Query Interface senao a e E aE PRE eE EErEE arene bah 83 33 3 Persist Interface siere iere EE ARE ATE ees 83 How To Create an Internal Connector sese ee eee eee 84 SAV PRETEQUISILES TTT 84 34 2 Creating a new connector project esse eee 84 34 3 Project e He TTT 85 34 4 Integrating the Connector into the OpenEngSB environment sese ee ee ee ee ee ee ee e 86 How To Create an Internal Domain sss sese sese sese ee ee ee ee ee ee eee 87 35D Prerequisites enini Seay naeio euy iea a a NE E aE A aE aa E EEO RASARE EERS 87 35 2 Creating a new domain project see eee eee 87 35 3 COMPONENTS A 2256 eeni nea a E Ea aE EDO ee E E EE ET Enk 89 354 CONNECTOLS ceisteanna r eaa ea a e aaa E a E E EEE EEE E ieaS 90 HowTo Extend OpenEngSB Console sss sese sese eee 91 SRP e 1 sa ecbes is cate A kos ngs See nhs Sede be E lon wu edad Geveo aaa dette aE E SE 91 36 2 Time to Complete neccen ii iii i i a decdeondicuaectecedaeasevedaners 91 36 3 N UE L 91 36 4 Start the Console soceri ia ieee es ea iiia i a iii i 91 36 5 Adding new commands sss sese sese eee eee 91 HowTo Create a connector for an already existing domain for the OpenEngSB 93 STL AGO all ec oire o ERE E ERA RE ERER Medea senders ae E EEEE 93 31 2 Time to Complete rros 3 iiei EE E EEEN EEEN EN 93 31 3 Prerequisites e ioeie E E EE ERE EEEE RAEE EREEREER 93 ER Step l Use the archety p rrei e EERE RRE REE O 93 37 5 Step 2s Add
126. values If it finishes successfully the new connector project is created and you may start implementing 34 3 Project Structure The newly created connector project should have the exact same structure as the following listing 85 How To Create an Internal Connector Te main java OE openengsb ED DIE E Or myconnector internal MyConnector Connector java MyConnector ConnectorProvider java MyConnector InstanceFactory java resources GL EN Blueprint myconnector mydomain context xml gt IAL Osa bundle properties bundle_de properties Diurd Lenk TOHO The myServiceConnector Class implements the interface of the domain and thus is the communication link between the OpenEngSB and the connected tool To give the OpenEngSB and in the long run the end user enough information on how to configure a connector the MyServiceInstanceFactory class provides the OpenEngSB with meta information for configuring and functionality for creating and updating a connector instances The MyServiceConnectorProvider class connects connector instances with the underlying OSGi engine and OpenEngSB infrastructure It exports instances as OSGi services and adds necessary meta information to each instance Since the basic functionality is mostly similar for all service managers the MyServiceConnectorProvider class extends a common base class Abst ractConnectorPro
127. vider In addition the Abst ractConnectorProvider also persists the configuration of each connector so that the connector instances can be restored after a system restart The blueprint setup in the resources folder contains the setup of the service manager Additional bean setup and dependency injection can be configured there The OpenEngSB has been designed with localization in mind The Maven Archetype already generates two bundle properties files one for English bundle properties and one for the German bundle_de properties language Each connector has to provide localization through the properties files for service and attributes text values This includes localization for names descriptions attribute validation option values and more For convenience the BundleSt rings class is provided on all method calls where text is needed for user representation for a specific locale 34 4 Integrating the Connector into the OpenEngSB environment The connector provided is responsible for the integration of the connector into the OpenEngSB infrastructure The correct definition of this service is critical 86 Chapter 35 How To Create an Internal Domain This chapter describes how to implement a domain for the OpenEngSB environment A domain provides a common interface and common events and thereby defines how to interact with connectors for this domain For a better description of what a domain exactly consists of take a look at the
128. wer and callld methodName gives the name of the method to call Args are the serialised parameters of the method classes are the types of the arguments This way it is easy to unmarshall the args into the appropriate classes metadata is a simple Map which stores key value pairs answer can simply be yes or no and denotes if the methodcall wants an answer to the call callld gives the return queue the caller will listen to for an answer An answer can have the type arg className and metaData properties type can be Object Exception or Void arg is the serialised form of the return argument className is the runtime class of the arg for deserialisation metadata is a simple key value store 21 1 1 1 HowTo call an external service via proxies This section will give a short introduction how to instantiate a proxy and call an external connector First you have to go to the TestClient to instantiate a new Proxy Select the Domain you want to have proxied and click New Proxy for that Domain s Example Domain New Proxy lt org openengsb domain example ExampleDomain This domain is provided as an example for all dev gt Logging Service Logs messages with a s Testclient new proxy link Then you have to set the correct values for the proxy properties The Service Id is a unique value that identifies the proxy in the OPENENGSB system The Port Id defines to Port to be used for sending the request jms json is a currently supported Port that
129. xtension mechanism AOP and the OSGi listener model the OpenEngSB directly extends the environment to provide own commands for the console fine grained security and a full grown workflow model These extensions are optional and not required if you want to use the platform alone Add or remove them as required for your use case 5 3 OpenEngSB Components These libraries are the OpenEngSB core The core is responsible to provide the OpenEngSB infrastructure as well as general services such as persistence security and workflows To provide best integration most of these components are tied to the OpenEngSB ESB environment Nevertheless feel free to add or remove them as required for your use case 5 4 OpenEngSB Tool Domains Although each tool provider gives a personal touch to its product their design is driven by a specific purpose For example there are many different issue trackers available each having its own advantages and disadvantages but all of them can create issues assign and delete them Tool Domains are based on this idea and distill the common functionality for such a group of tools into one Tool Domain interface and component Tool domains could be compared best to the concept of abstract classes in in object orientated programming languages Similar to these they can contain code workflows additional logic and data but they are useless without a concrete implementation Together with the ESB the OpenEngSB infrastructure and
130. y checking the event log displayed on the page and create rules manually in the editor below The rules are written in plain text based on Drools documentation and Java standards They are quickly understood just take a look at the auditEvent rule used to generate the event log displayed on top of the page You can display the rule by choosing Rule in the left most drop down box and org openengsb auditEvent in the second one The text editor now shows that there is a when section that acts as filter for incoming events and there is a then section that describes the actions to be taken in case of a match Rule x buildStarted save cancel when Event type BuildStartEvent then System out printin build started build started rule Let us start out and create our own rule We will inform the user via console when a build process starts Click the new button next to the drop down boxes enter a name for the newly created rule i e buildStarted and save it After selecting the rule in the drop down box the text editor actually shows the same content as for the audit event Do not be confused it s the default template You can start editing right away Note Writing output directly to the console without using a logger service is considered bad practice Yet it s simple and sufficient for demonstration purposes 59 HowTo Integrate services with OpenEngSB when Event type BuildStartEvent then Syste
131. y sending a message to yourself Again the call was successful if you receive a message with the prefix of the notifier you ve chosen in the context Congratulations you have just finished the first implementation HowTo of Open Engineering Service Bus 18 7 Next Steps Now that you ve finished the most easy OpenEngSB use case go on with a more complex one Events 36 Chapter 19 HowTo Events with the OpenEngSB Using the logging service 19 1 Goal This tutorial shows how the event system in the OpenEngSB can be used Therefore a log and a domain connector are created and configured The context system in the OpenEngSB is used to define which connectors should be used and a simple event is used starting a rule 19 2 Time to Complete If you are already familiar with using services in OpenEngSB about 30 minutes see HowTo First steps 19 3 Prerequisites This HowTo assumes you are already familiar with using and configuring services in OpenEngSB 19 4 Create required connectors Now one logging service and one email service should be created Create one notification service as described in the previous example Please name it notification instead of est or test2 Now create a logging service 1 0 0 SNAPSHOT gaco oot SIS Poss Home Test Client Send Event Page Context Services Current Project foo Y logout Creating new Logging Service Logs messages with a specific log level to the OSGi lo

PDF documentation

Contents

Download Pdf Manuals

Related Search

Related Contents