CHOReOS Enactment Engine User Guide - IME-USP
Contents
1. 3 5 Choreographing services that are already 3 6 SOAP service type s sara E aaa ewe RA VR e ORO a ea es 3 1 COORDEL service type segue p RR ets e ecu le Ba ee em dius 3 8 Coding guidelines b 2 A RSS RS ES buco Eus 4 Extending Enactment Engine Introduction 4 e ee Be eee AN ee Ru exque ug 4 2 Supporting new cloud providers 4 4 Supporting new service types 4 5 Supporting new node selection policies 5 Elasticity and QoS management 00 NN NOAA Ct CONTENTS Chapter 1 Installation Guide 1 1 Introduction The CHOReOS Enactment Engine EE provides a Platform as a Service PaaS that automates the distributed deployment of service choreographies in cloud environments This chapter is targeted mainly to EE administrators providing instructions about how to install configure and run the Enactment Engine We will describe now each one of the components running on the Enactment Engine execution envi ronment They are depicted in Fig 1 1 Infrastructure provider creates and destroys virtual machines also called nodes in a cloud comput ing environment Currently only Amazon EC2 and OpenStack are supported as infrastructure providers but the Enactment Engine can be extended to support other virtualization technologies Chef solo is installed by the Enactment2. CHAPTER 2 ENACTMENT ENGINE API lt lt Enum gt gt PackageType lt lt Enum gt gt COMMAND_LINE service Typs ServiceDependency TOMCAT SOAP 0 amp serviceSpecName String serviceSpecRole String DeployableServiceSpec endpointName String port int nodeld String cloudAccount String ip String numberOfinstances int hostname String resourcelmpact Resourcelmpact Selected nodes Servicelnstace 1 packageuUri String packageType String LegacyServiceSpec uris List lt String gt version String Service LegacyServicelnstance ChoreographySpec uuid String LegacyService uris List String instanceld String uri String DeployableService Choreography Figure 2 1 Enactment Engine REST API data model 2 2 DATA MODEL 13 To request a choreography deployment it is important to understand very well the ServiceSpec DeployableServiceSpec and the LegacyServiceSpec classes Therefore the description of them fol lows 1 ServiceSpec name a unique character sequence within the choreography specification type whether the service is a SOAP service or a REST service More types can be added as necessary roles list of roles implemented by the service dependencies list of ServiceDependency entries each entry describes the name o
3. gt XS i 1 xs 1 lt xs element minOccurs 0 name ip type xs string lt xs element minOccurs 0 name privateKeyFile type xs string gt XS i 1 lt xs element minOccurs 0 name ram type xs int gt XS i e XS i lt xs element minOccurs 0 name so type xs string XS i xs i lt xs element minOccurs 0 name state type xs int lt xs element minOccurs 0 name storage type xs int lt xs element minOccurs 0 name user type xs string gt lt xs element minOccurs 0 name zone type xs string gt lt xs sequence gt lt xs complexType gt xs complexType name serviceInstance gt lt xs sequence gt lt xs element minOccurs 0 name instanceld type xs string gt lt xs element minOccurs 0 name nativeUri type xs string gt lt xs element minOccurs 0 name node type cloudNode gt lt xs element minOccurs 0 name serviceSpec type deployableServiceS pec gt lt xs sequence gt lt xs complexType gt lt xs complexType name legacyService gt lt xs complexContent gt xs extension base service gt lt xs sequence gt lt xs element maxOccurs unbounded minOccurs 0 name legacyServiceInstances nillable true type legacyServiceInstance gt lt xs sequence gt
4. Expose gt Action Service Configuration Listing 3 8 LTS file of a simple coordination delegate that acts as a proxy endpoint WeatherForecastServicePort 3 5 Choreographing services that are already running A service choreography can be composed of services that are running before the choreography deployment Although a service like this do not need to be deployed by the middleware it must be declared on the choreography specification with the LegacyServiceSpec class The URIs attribute must contain the list of URIs where the multiple replicas of the service are accessible which will be used by the middleware to invoke the setInvocationAddress operation of other services 3 6 SOAP service type By convention services of this type must provide an operation named setInvocationAddress this operation is used to inform the service about the remote service endpoints that implement the various roles it depends on The setInvocationAddress arguments are the following dependency role defines the operations provided by the dependency A service may depend on mul tiple services with different roles so this argument is necessary to the service know how to use the received dependency It is a requirement that the service must to know the available operations of each role from which it depends The role of each service must be also defined in the choreography specification that is the Enactment Engine input and chor
5. It is possible to parse the output to find out failed deployments which will be the services without associated nodes Update a choreography only partially implemented at this time HTTP Method URI Request body Responses 200 OK location chors id Body Choreography XML representation ChorSpec XML representation see Listing 2 2 PUT 400 BAD REQUEST 404 NOT FOUND 500 ERROR This operation has the same behavior of the create choreography operation To apply the changes it is necessary to invoke the deployment operation again When the new deployment is invoked the Enactment Engine will detect the changes that have been inserted in the choreography and deploys new services remove unneeded services and redeploy services where some aspect such as version number number of instances etc has changed Currently the only detected changes are increased or decreased number of instances and increased or decreased memory consumption Services on the old and new versions of the choreography are correlated by means of the name attribute of ServiceSpec 2 4 Java client In the EnactmentEngineAPI project there is the EEClient class which implements the EnactmentEngine interface Listing 2 3 and handles the REST communication with the Enactment Engine server This means you can invoke the Enactment Engine by using a simple Java object without worrying with XML details Listing 2 3 Enactment Engine Java i
6. Listing 4 1 CloudProvider interface public interface CloudProvider public String getCloudProviderName public CloudNode createNode NodeSpec nodeSpec throws NodeNotCreatedException public CloudNode getNode String nodeld throws NodeNotFoundException public List lt CloudNode gt getNodes public void destroyNode String id throws NodeNotDestroyed NodeNotFoundException public CloudNode createOrUseExistingNode NodeSpec nodeSpec throws NodeNotCreatedException public void setCloudConfiguration CloudConfiguration cloudConfiguration Implementations should use the cloudConfiguration object to retrieve configuration properties sup plied by EE administrators Such properties usually encompass user credentials to access the infras tructure provider service and options such as VM types or images The cloudConfiguration object is injected into the cloud provider instance by the EE 35 CONDO WN 1 36 CHAPTER 4 EXTENDING ENACTMENT ENGINE Important note in the current implementation Enactment Engine is tailored to work with nodes running Ubuntu 12 04 Therefore CloudProvider implementors should provide Ubuntu 12 04 nodes The next step is to edit the extensible cloud_providers properties file located EnactmentEngine resources folder You must add a line in the format NAME full qualified class name where the key is just an alias that you can freely define since it does not conflict with other e
7. lt xs extension gt lt xs complexContent gt lt xs complexType gt xs complexType name legacyServiceInstance gt lt xs sequence gt lt xs element minOccurs 0 name spec type legacyServiceSpec gt lt xs element minOccurs 0 name uri type xs string gt lt xs sequence gt lt xs complexType gt lt xs simpleType name memoryType gt xs restriction base xs string gt xs enumeration value SMALL gt xs enumeration value MEDIUM gt lt xs enumeration value LARGE gt lt xs restriction gt lt xs simpleType gt lt xs schema gt 24 CHAPTER 2 ENACTMENT ENGINE API 00 3 gt Chapter 3 How to package services to be deployed by the Enactment Engine 3 1 Introduction There are two main attributes in the DeployableServiceSpec class that define constraints on how a service must be coded and packaged The packageType attribute defines which kind of deployable package is expected by the Enactment Engine and therefore the process of deploying and running the specified service Examples of package types are COMMAND LINE and TOMCAT The serviceType attribute defines the process of invoking the specified service which is used by the Enactment Engine to properly invoke the setInvocationAddress operation during deployment Examples of service types are SOAP and REST types although only SOAP services are current
8. type xs int gt lt xs element minOccurs 0 ref resourcelmpact gt lt xs element minOccurs 0 name version type xs string gt lt xs sequence gt lt xs extension gt lt xs complexContent gt lt xs complexT ype gt xs complexType abstract true name serviceSpec gt lt xs sequence gt lt xs element maxOccurs unbounded minOccurs 0 name dependencies nillable true type serviceDependency gt lt xs element minOccurs 0 name type xs string gt lt xs element maxOccurs unbounded 0 name roles nillable true type xs string gt lt xs element minOccurs 0 name serviceType type serviceType gt lt xs sequence gt lt xs complexType gt xs complexType name desiredQoS gt lt xs sequence gt lt xs element minOccurs 0 name responseTimeMetric type responseTimeMetric gt lt xs sequence gt lt xs complexT ype gt lt xs complexType name responseTimeMetric gt lt xs sequence gt lt xs element name acceptablePercentage type xs float gt lt xs element name maxDesiredResponseTime type xs float gt lt xs sequence gt lt xs complexType gt xs complexType name packageType gt lt xs sequence gt lt xs element minOccurs 0 name type type xs string gt lt xs sequence gt lt
9. xs complexT ype gt xs complexType name resourcelmpact gt lt xs sequence gt lt xs element minOccurs 0 name memory type memoryType gt 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 2 5 CHOREOGRAPHY XML SCHEMA DEFINITION XSD FILE 21 lt xs element minOccurs 0 name cpu type xs string gt lt xs element minOccurs 0 name storage type xs string gt lt xs element minOccurs 0 name network type xs string gt lt xs sequence gt lt xs complexType gt xs complexType name serviceDependency gt lt xs sequence gt lt xs element minOccurs 0 name serviceSpecName type xs string gt lt xs element minOccurs 0 name serviceSpecRole type xs string gt lt xs sequence gt lt xs complexType gt lt xs complexType name serviceType gt lt xs sequence gt lt xs element minOccurs 0 name type type xs string gt lt xs sequence gt lt xs complexType gt lt xs complexType name legacyServiceSpec gt lt xs complexContent gt xs extension base serviceSpec gt lt xs sequence gt lt xs element u
10. 79 80 81 82 83 84 85 87 88 89 90 91 92 93 94 95 96 97 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 16 CHAPTER 2 ENACTMENT ENGINE API lt serviceSpecRole gt airline lt serviceSpecRole gt lt dependencies gt lt name gt travelagency lt name gt lt roles gt travelagency lt roles gt lt serviceType gt lt type gt SOAP lt type gt lt serviceType gt lt endpointName gt travelagency lt endpointName gt numberOfInstances 1 numberOfInstances lt packageType gt lt type gt COMMANDLINE lt type gt lt packageType gt lt packageUri gt http valinhos ime usp br 54080 enact_test v3 TravelAgency 3 0 0 jar lt packageUri gt lt port gt 1235 lt port gt lt resourcelmpact gt lt version gt 0 1 lt version gt lt serviceSpec gt lt serviceInstances gt lt deployableServices gt lt deployableServices gt spec xsi type deployableServiceSpec xmlns xsi http www w3 org 2001 XMLSchema instance gt lt name gt airline lt name gt lt roles gt airline lt roles gt lt serviceType gt lt type gt SOAP lt type gt lt serviceType gt lt endpointName gt airline lt endpointName gt numberOfInstances 1 numberOfInstances lt packageType gt type COMMAND LINE lt type
11. XML Binding JAXB allows Java developers to map Java classes to XML representations 10 12 13 14 15 16 17 18 19 20 21 22 23 25 26 27 28 29 30 31 32 33 34 35 37 38 39 40 Al 42 43 44 45 46 4T 48 49 50 51 52 53 54 55 56 2 2 DATA MODEL 15 lt endpointName gt airline lt endpointName gt lt numberOfInstances gt I lt numberOfInstances gt lt packageType gt ty pe gt COMMAND LINKX t y pe lt packageType gt lt packageUri gt http valinhos ime usp br 54080 enact_test v3 Airline 3 0 0 jar packageUri lt gt 1234 lt port resourceImpact lt version gt 0 1 lt version gt lt deployableServiceSpecs gt lt deployableServiceSpecs gt lt dependencies gt lt serviceSpecName gt airline lt serviceSpecName gt lt serviceSpecRole gt airline lt serviceSpecRole gt lt dependencies gt lt name gt travelagency lt name gt lt roles gt travelagency lt roles gt lt serviceType gt lt type gt SOAP lt type gt lt serviceType gt lt endpointName gt travelagency lt endpointName gt numberOfInstances 1 numberOfInstances lt packageType gt lt type gt COMMANDLINE lt type gt lt packageType gt lt packageUri gt http valinhos ime usp br 54080 enact_test v3 TravelAgency 3 0 0 jar packageUri lt gt 1235 lt port resourceImpact gt lt version gt 0 1 lt version gt lt deployableServiceSpecs gt lt choreographySpe
12. break registryHelper getChorClient updateChoreography id cSpec registryHelper getChorClient enactChoreography id
13. gt gt Classpath variables and set the M2 REPO variable pointing to your Maven repository folder usually the m2 repository folder within your home folder Obs we have used the Eclipse Indigo version Another way is using maven EnactmentEngine mvn exec java If you successfully start the EE you must see the following message on the console Enactment Engine has started http localhost 9102 enactmentengine To verify if it is everything OK run the org ow2 choreos chors SimpleChorEnactmentTest This test will deploy a simple choreography composed of two services and try to invoke it 10 CHAPTER 1 INSTALLATION GUIDE Chapter 2 Enactment Engine API 2 1 Introduction This chapter provides detailed information about the Enactment Engine REST API and its target mainly to choreography deployers Understanding the API enables you to write your own code to enact a choreography This chapter is organized as follows Section 2 2 presents the data model that defines XML represen tations exchanged by API messages Section 2 3 describes all the operations provided by the REST API detailing parameters and return structures Section 2 4 presents our client implementation that can be used within any Java program 2 2 Data model As in any API Enactment Engine operations receive and return complex data structures representing real world concepts Figure 2 1 presents these concepts in the UML notation Although the REST API handles XML r
14. on other services is a consumer service and the service that provides functionality to the dependent service is the provider In simple service compositions such dependency relations are hardcoded on consumer services But decoupling the consumer service implementation from the actual provider endpoint is a good practice which enables dynamic adaptation Moreover dependency hardcoding is not possible on cloud environments since we do not know service addresses before deployment Therefore in the CHOReOS environment each consumer service is declared as depending on roles rather than other service implementations The consumer service must receive the actual provider endpoint of a service fulfilling the required role through the setInvocationAddress operation which every consumer service must implement The Enactment Engine will use ServiceDependency data to know which calls it must perform to the setInvocationAddress operation of participant services Thus the Enactment Engine will be able to tell for example to ServiceA that it must use ServiceB as 0161 where ServiceB is the list of endpoint URIs corresponding to the multiple instances of ServiceB In this way the CHOReOS middleware provides a dependency injection mechanism to wire up service dependencies Obs to SOAP services the URI passed to the setInvocationAddress operation does not contain the wsdl suffix When the package type is COMMAND LINE the service will be executed
15. set Name TRAVEL AGENCY setServiceType ServiceType SOAP set PackageType PackageType COMMAND LINE set PackageUri TRAVEL AGENCY JAR set Port TRAVEL AGENCY PORT setEndpoint Name TRAVEL AGENCY setRoles Collections singletonList TRAVEL AGENCY endency dependency new ServiceDependency dependency setServiceSpecName AIRLINE dependency setServiceSpecRole AIRLINE travelSpec addDependency dependency Finally Listing 2 6 is an example of how to use the Java API to invoke the EE Listing 2 6 Deploying a choreography using the Java API public class Deployment public static void main String args throws DeploymentException ChoreographyNotFoundException final String EE URI http localhost 9102 enactmentengine EnactmentEngine ee new EnactmentEngineClient EE_URI ChorSpecExample example new ChorSpecExample ChoreographySpec chorSpec example getChorSpec 10 11 13 14 15 N 00 1 11 12 13 14 16 17 18 19 20 21 23 24 25 26 27 29 30 31 32 33 34 SAL AA A RA 60 JO Ou 5 20 CHAPTER 2 ENACTMENT ENGINE API String chorld ee createChoreography chorSpec Choreography chor ee deployChoreography chorId System out println chor checking output 2 5 Choreography XML Schema Definition XSD file ChorSpec XSD lt xml version 1 0 encoding UTF 8 gt lt
16. triggered as a client for the Enactment Engine it requests modifications to running choreographies by sumitting updated Choreography Deployers when notifications are received from the monitoring subsystem An example of such a daemon is available in the Enactment Engine source code repository in the reconfiguration directory We show below some code snippets from this example daemon and explain its general mechanism During startup the daemon loads predefined rules from a static file and submits them to the Glimpse monitor public static void main String args String rules Manager ReadTextFromFile this getClass getClassLoader getResource rules SLAViolations xml getFile new EnactmentEngineGlimpseConsumer properties rules Whenever a rule is triggered the daemon is notified and runs the code from a class whose name is contained in the notification event public void messageReceived Message argO ObjectMessage responseFromMonitoring ObjectMessage response ComplexEventResponse responseFromMonitoring getObject event new HandlingEvent response getResponseValue response getRuleName Class lt ComplexEventHandler gt theClass theClass Class lt ComplexEventHandler gt Class forName org ow2 choreos chors reconfiguration events event getEventData handler theClass newInstance handler handleEvent event The submitted example rules define that whenever mo
17. 4 Extending Enactment Engine 4 1 Introduction Current PaaS solutions available on market are well known for their low flexibility Some of them work only on a specific cloud environment others only with a few development frameworks Enactment Engine tries to overcome this issue by providing an extensible architecture Although the out of box version of Enactment Engine is quite limited with some programming is possible to extend it to provide support to new 2 cloud providers ii package types iii service types and iv node selection policies By extending we mean no current Enactment Engine code need to be changed and that each new extension can be implemented by the means of a well defined process which are now described in this section 4 2 Supporting new cloud providers In Enactment Engine cloud providers are just a source of virtual machines provisioning Any technology able to create new virtual machines may be used as cloud provider To implement a new cloud provider it is necessary to implement the CloudProvider interface List ing 4 1 Current implementations are AWSCloudProvider that uses EC2 service OpenStackKeystoneCloud Provider and FixedCloudProvider that always points to the same user defined VMs An example of new cloud provider implementation could be the VirtualBoxCloudProvider that would use VirtualBox on the developer machine to create new VMs this is an example more suited to test environments
18. 5 to Tomcat the ports used by your JAR services and the port 8180 to EasyESB 6 CHAPTER 1 INSTALLATION GUIDE IN Amazon EC2 OpenStack etc Infrastructure provider Enactment Engine creates SCP SSH Target node EE client EE Chef Solo deploys Figure 1 1 Enactment Engine execution environment 1 3 1 Amazon EC2 Amazon EC2 service is the simplest choice to dynamically retrieve VMs as you need You need just to create an account at http aws amazon com and configure a pair of keys to access the VMs through SSH The trade off is that you must pay to Amazon Some hints e Request credits to education purposes http aws amazon com grants The first of us earned 500 but the others 100 Maybe it depends on your research project description e Initially there is a limit of 20 VMs that you can run simultaneously e Request to increase Amazon EC2 instance limit http aws amazon com contact us ec2 request At USP we got a 50 VMs limit e If you are going to use the EC2 API directly pay attention to the one second rule http www a2sdeveloper com page working with the one second rule html Nonetheless Enactment Engine already implements the enforcement of this rule e As you will be charged per hour don t forget to shutdown stop unused VMs e You can use the Amazon EC2 web console to unblock TCP ports necessary to the choreography execution e You can also use the ec2 command lin
19. 9 190 22 CHAPTER 2 ENACTMENT ENGINE API lt xs element name port type xs int gt lt xs element minOccurs 0 ref resourcelmpact gt lt xs element minOccurs 0 name version type xs string gt lt xs sequence gt lt xs extension gt lt xs complexContent gt lt xs complexType gt xs complexType abstract true name serviceSpec gt lt xs sequence gt lt xs element maxOccurs unbounded minOccurs 0 name dependencies nillable true type serviceDependency gt lt xs element 0 name type xs string gt lt xs element maxOccurs unbounded 0 name roles nillable true type xs string gt lt xs element minOccurs 0 name serviceType type serviceType gt lt xs sequence gt lt xs complexType gt lt xs complexType name desiredQoS gt lt xs sequence gt lt xs element minOccurs 0 name responseTimeMetric type responseTimeMetric gt lt xs sequence gt lt xs complexType gt xs complexType name responseTimeMetric gt lt xs sequence gt lt xs element name acceptablePercentage type xs float gt lt xs element name maxDesiredResponseTime type xs float gt lt xs sequence gt lt xs complexType gt xs complexType name packageType gt lt xs sequence gt lt xs element minOc
20. AR packages thanks to the management utilities of Tomcat Life cycle management matters for example when debugging if a service is actually running or not Handling the life cycle of JAR packaged services requires directly handling Unix processes e Never use absolute paths to retrieve resources since the service will not run in the same machine where it was compiled A good way to access resources is using the getResourceAsStream method of the current class loader e When starting a JAR packaged service do not use the localhost address to create the endpoint since the service will be not remotely accessible Instead use the address 0 0 0 0 that will make your service listen in every possible address in the machine including the localhost This practice makes the service accessible from other machines e Do not use System out println use a log tool instead Since the services are deployed in an automated way it might be impossible to retrieve the console output which will make debugging harder Using a logger as Log4j for example makes the service record its messages in a file which helps developers and operators in debugging e Do not forget to validate the WSDL files of your web services specially if there is some manual edition applied on them Shttp docs oracle com javase 6 docs api java lang ClassLoader html getResourceAsStream java lang String 3 8 CODING GUIDELINES 33 e Ensure that t
21. CHOReOS Enactment Engine User Guide Version 4 1 Leonardo Leite Thiago Furtado Nelson Lago IME USP March 2 2014 Contents 1 Installation Guide LI Introductions nce a EMO Xx SWR e 1 2 Requirements een ae bee ede Te ee RR Roe PR RU AIR 1 37 Cloud Rroyider a utut teuer ele RUE Ses uod weeds al mde qd up p RE 1 31 Amazon BG2 exe ea L3 2 OpenStack ebbe dE oe etn Read x Aes 1 3 3 Fixed cloud provider e s e sa 1 4 Checkout and 1 5 Configurations c Re t ee PAP Es 1 6 Execution sa 7 se a ed bx we Bow RAF ede esq HR de deos 2 Enactment Engine API PI Introductionis ur rtu se m a f ul a Ge Lows Nt rr etus de Se 2 2 Datazniodel Sua oie ee teh host er Eee nedum SUE d eate us hl 2 9 RESTSABI 28265 4449 eso dy b S MUS ee LH eg E DA Javaselienb4 22 2 EH oA erui RUE ALARM Rue RU de 2 5 Choreography XML Schema Definition XSD 3 How to package services to be deployed by the Enactment Engine 3 1 Introduction woo cud eee REUS uu dos x EA o IMPR 3 2 COMMAND LINE package type 3 9 packe type 00 0 y us RR Ru y m RE dore AO 34 EASY ESB package type
22. Engine in each cloud node to manage recipes execution Chef recipes are scripts written in a Ruby like Domain Specific Language that implement the process of configuring operational system installing required middleware and finally deploying the services EE cliente is a script written by deployers that specifies the choreography deployment and invokes the EE to trigger the deployment process Deployer is the human operator responsible by the deployment process Enactment Engine deploys choreography services according to the specification sent by the client 1 2 Requirements Before you run Enactment Engine you will need e Git e Java 6 or later we are using OpenJDK e Maven 3 http maven apache org download html e access to Infrastructure Provider services as detailed in Section 1 3 1 3 Cloud Provider A CloudProvider is an Enactment Engine interface that specifies methods to CRUD virtual machines It is expected that a Cloud Provider implementations will act just as a client of some Infrastructure Provider In this section we describe the currently available CloudProvider implementations and how to use them New CloudProviders may be implemented to support other virtualization tools One example would be creating a VirtualBoxCloudProvider to create VMs using VirtualBox Whatever the cloud provider you choose ensure that the required TCP ports of the created VMs are unblocked Required ports 22 to SSH 8080 8009 and 800
23. Listing 3 5 Example of web xm1 file lt xml version 1 0 encoding UTF 8 gt lt DOCTYPE web app PUBLIC Sun Microsystems Inc DID Web Application 2 3 EN http java sun com dtd web app_2_3 dtd gt lt web app gt lt listener gt lt listener class gt com sun xml ws transport http servlet WSServletContextListener lt listener class gt lt listener gt lt servlet gt lt servlet name gt airline lt servlet name gt lt servlet class gt com sun xml ws transport http servlet WSServlet lt servlet class gt lt load on startup gt 1 lt load on startup gt lt servlet gt lt servlet mapping gt lt servlet name gt airline lt servlet name gt lt url pattern gt airline lt url pattern gt lt servlet mapping gt lt session config gt lt session timeout gt 120 lt session timeout gt lt session config gt lt web app gt 3 4 EASY ESB package type The Enactment Engine is also responsible for the coordination delegates deployment that are executed by the EasyESB service bus To enable this functionality we have created the EASY ESB package type that is a tar gz package containing a config xml file with instructions for the bus In the package some resources needed for the deployment can be added This process enables not only the deployment of coordination delegates but actually any interaction with EasyESB The confi
24. M 1 5 192 168 56 101 192 168 56 102 MY CLUSTER FIXED VM PRIVATE SSH KEYS home leonardo ssh nopass home leonardo ssh nopass CLUSTER FIXED VM USERS choreos choreos My_AWS_ACCOUNT CLOUD PROVIDER AWS AWS ACCOUNT AMAZON ACCESS KEY ID SECRET MY AWS ACCOUNT AMAZON SECRET KEY SECRET MY_AWS_ ACCOUNT AMAZON KEY PAIR leoflaws MY_AWS_ ACCOUNT AMAZON PRIVATE SSH KEY home leonardo ssh leoflaws pem MY AWS ACCOUNT AMAZON IMAGE ID us east 1 ami 1ccc8875 MY OPENSTACK ACCOUNT CLOUD PROVIDER OPEN STACK MY OPENSTACK ACCOUNT OPENSTACK KEY PAIR 1eo fl MY OPENSTACK ACCOUNT OPENSTACK PRIVATE SSH KEY home leonardo ssh nopass MY OPENSTACK ACCOUNT OPENSTACK TENANT CHOReOS Sandbox MY OPENSTACK ACCOUNT OPENSTACK USER 1e o fl MY OPENSTACK ACCOUNT OPENSTACK PASSWORD SECRET MY OPENSTACK ACCOUNT OPENSTACK IP http 172 15 237 10 5000 v2 0 OPENSTACK ACCOUNT OPENSTACK IMAGE ID RegionOne 1654b5b6 49b7 4039 b7b7 0e42e85480f4 The options to NODE SELECTOR are ALWAYS CREATE a new VM is created to each deployed service instance ROUND ROBIN NodeSelector makes a round robin using the available VMs without creating any new VM usually it makes sense to use it only when using the fixed cloud provider LIMITED ROUND ROBIN initially the NodeSelector behaves like the ALWAYS CREATE until a limit of created VMs is reached VM LIMIT After this limit the selector behaves like the ROUND
25. ROBIN When using this selector it is necessary to declare the integer VM LIMIT prop erty in the configuration file The AMAZON IMAGE ID enables you to specify a customized image to be used by Enactment Engine This feature is intended to use an image of a node already bootstrapped In this way the bootstrap process becomes much faster The same may be applied to the OPENSTACK IMAGE ID But in both cases the image must still provide an Ubuntu Server 12 04 system At the clouds properties each cloud account is configured by a group of properties grouped by a common prefix Let s call this prefix as cloud account name These cloud account names will be compared with the owner attribute in the service specifications so a service can be specified to be deployed under a specific cloud account If there is no match the DEFAULT CLOUD ACCOUNT value declared on ee properties will be used as cloud account name Attention inline comments are not allowed in properties files Therefore the following would not work VMN LIMIT 3 Mt how many instances we can afford to pay 1 6 Execution After compiling the project to run the Enactment Engine you have just to run the main method on the class org ow2 choreos ee rest EnactmentEngineServer 1 6 EXECUTION 9 This task can be easier accomplished if you import the Enactment Engine projects in the Eclipse IDE After importing the project open the menu Window gt gt Preferences gt gt Java gt gt Build Path
26. ServiceConfigurationType gt lt sequence gt lt complexType gt lt complexType name ServiceConfigurationType gt lt sequence gt lt element maxOccurs unbounded name Action type tns ActionType gt lt sequence gt lt attribute name url type string gt lt complexType gt lt complexType name ActionType gt lt choice gt lt element name Deploy type tns DeployType gt lt element name Bind type tns BindType gt lt element name Expose type tns ExposeType gt lt element name Proxify type tns ProxifyType gt lt element name AddNeighbourNode type tns AddNeighbourNodeType gt lt choice gt lt complexType gt lt complexType name AddNeighbourNodeType gt lt sequence gt lt element name NeighbourAdminAddress type string gt lt sequence gt lt complexType gt lt complexType name DeployType gt lt sequence gt lt element name MainResource type string gt lt element maxOccurs unbounded name Resource string gt yP 5 lt sequence gt lt complexType gt lt complexType name BindType gt lt sequence gt lt element name Url string gt lt element name Wsdl type string gt lt sequence gt lt complexType gt lt complexType name ExposeType gt lt sequence gt lt elem
27. The value of the EndpointName element line 22 must correspond to the name of the portType element in the coordination delegate WSDL The Its file pointed by the config xml is provided in the Listing 3 8 and the value of its endpoint attribute must correspond to the name of the portType element in the already running service WSDL Listing 3 7 Example of config xml that deploys a coordination delegate lt xml version 1 0 enc begin lstlisting oding UTF 8 gt Configuration xmlns http ebmwebsourcing com cli schema xmlns xsi http www w3 org 2001 XMLSchema instance xsi schemaLocation http ebmwebsourcing com cli schema conf schema xsd gt Service url http localhost 8180 services adminExternalEndpoint gt Action lt Deploy gt lt MainResource gt weatherforecastservice Its lt MainResource gt lt Resource gt cdweatherforecastservice wsdl lt Resource gt lt Deploy gt lt Action gt lt Action gt lt Bind gt lt Url gt http 192 168 56 101 8192 weatherforecastservice lt Url gt lt Wsdl gt http 192 168 56 101 8192 weatherforecastservice wsdl lt Wsdl gt lt Bind gt lt Action gt lt Action gt lt Expose gt lt ServiceNamespace gt http services choreos org lt ServiceNamespace gt lt ServiceName gt WeatherForecastServiceService lt ServiceName gt lt Endpoint Name gt CD WeatherForecastServicePort lt EndpointName gt lt
28. ame is airline Attention The use of 0 0 0 0 instead of localhost is necessary to make the service accessible from outside the machine where it is running Listing 3 1 Example of a class with the main method within a JAR file package org ow2 choreos import javax xml ws Endpoint public class AirlineStarter public static final String SERVICE ADDRESS http 0 0 0 0 1234 airline private static Endpoint endpoint public static void start Airline service new AirlineService endpoint Endpoint create service 25 13 14 15 16 17 18 19 m 26 CHAPTER 3 HOW TO PACKAGE SERVICES endpoint publish SERVICE ADDRESS public static void main String args start Runnable JARs can be easily generated by the export menu in Eclipse or by Maven To generate a runnable JAR using Maven 3 add the excerpt in the Listing 3 2 in your pom xml file properly replacing the content of the mainClass element In this way when generating the JAR file mvn package Maven will be in charge of properly generating the MANIFEST file Listing 3 2 Excerpt of pom file to generate a runnable JAR using Maven 3 lt build gt lt finalName gt airline service lt finalName gt lt lt finalName gt travel agency service lt finalName gt lt lt plugins gt lt plugin gt lt groupld gt org apache maven plugins lt groupld gt lt artifactId gt m
29. aven shade plugin lt artifactId gt lt version gt 2 0 lt version gt lt executions gt lt execution gt lt phase gt package lt phase gt lt goals gt lt goal gt shade lt goal gt lt goals gt lt configuration gt lt shadedArtifactId gt airline service lt shadedArtifactId gt lt shadeSourcesContent gt true lt shadeSourcesContent gt lt transformers gt lt transformer implementation org apache maven plugins shade resource ManifestResourceTransformer gt lt mainClass gt org ow2 choreos AirlineStarter lt mainClass gt lt transformer gt lt transformers gt lt configuration gt lt execution gt lt executions gt lt plugin gt lt plugins gt lt build gt An important issue about using JAR packages is that the Enactment Engine is not able to prevent TCP port conflicts Therefore try to avoid the use of the same port in multiple services Also be sure that the required ports are not blocked by the cloud infrastructure However a better way to prevent such port issues is not to use JAR packages but use WAR packages instead 3 3 TOMCAT package type Services whose package type are specified as TOMCAT must be provided as WAR packages The Enact ment Engine will be in charge of deploying and starting a Tomcat instance or select an already running instance and then deploying the WAR package onto the selected instance If the service port is not specified in the service specification t
30. by the java jar command Dependency Injection pattern by Martin Fowler http martinfowler com articles injection html 004 00 10 14 CHAPTER 2 ENACTMENT ENGINE API Resource impact specification The DeployableServiceSpec class has also an attribute to specify non functional requirements This attribute is called resource impact and it can be used by the NodeSelector to choose the node in which the service should be deployed NodeSelector will try to choose a node that enables the service to fulfil such requirements This attribute is not described in this document because its structure is not fully defined yet But it is expected to define among others required values of CPU memory and disk usage XML representation Each class is mapped to and from an XML representation according to the default behaviour of the JAXB To properly build and read these XML representations you can rely on the schema definition Section 2 5 We provide here an example of ChorSpec Listing 2 1 and Choreography Listing 2 2 XML representations to a little choreography with just two services airline and travel agency services Listing 2 1 ChorSpec XML representation example lt choreographySpec gt lt deployableServiceSpecs gt lt name gt airline lt name gt lt roles gt airline lt roles gt lt serviceType gt lt type gt SOAP lt type gt lt serviceType gt lt endpointName
31. c gt lt deployableServices gt spec xsi type deployableServiceSpec xmlns xsi http www w3 org 2001 XMLSchema instance gt lt dependencies gt lt serviceSpecName gt airline lt serviceSpecName gt lt serviceSpecRole gt airline lt serviceSpecRole gt lt dependencies gt lt name gt travelagency lt name gt lt roles gt travelagency lt roles gt lt serviceType gt lt type gt SOAP lt type gt lt serviceType gt lt endpointName gt travelagency lt endpointName gt lt numberOfInstances gt I lt numberOfInstances gt lt packageType gt lt ty pe gt COMMAND LINEc t y pe lt packageType gt packageUri http valinhos ime usp br 54080 enact test v3 TravelAgency 3 0 0 jar lt packageUri gt lt port gt 1235 lt port gt resourceImpact gt lt version gt 0 1 lt version gt lt spec gt lt UUID gt 9 fb5c93a b4d1 4a56 9b4b 120e89681e31 lt UUID gt lt selectedNodes gt lt hostname gt choreos node lt hostname gt lt id gt 2 lt id gt lt ip gt 192 168 56 102 lt ip gt lt selectedNodes gt lt servicelnstances gt lt instanceld gt travelagencyl lt instanceld gt lt nativeUri gt http 192 168 56 102 1235 travelagency lt nativeUri gt lt node gt lt hostname gt choreos node lt hostname gt lt id gt 2 lt id gt lt ip gt 192 168 56 102 lt ip gt lt node gt lt serviceSpec gt lt dependencies gt lt serviceSpecName gt airline lt serviceSpecName gt 78
32. curs 0 name type type xs string gt lt xs sequence gt lt xs complexT ype gt xs complexType name resourcelmpact gt lt xs sequence gt lt xs element minOccurs 0 name memory type memoryType gt lt xs element minOccurs 0 name type xs string gt lt xs element minOccurs 0 name storage type xs string gt lt xs element minOccurs 0 name network type xs string gt lt xs sequence gt lt xs complexType gt xs complexType name serviceDependency gt lt xs sequence gt lt xs element minOccurs 0 name serviceSpecName type xs string gt lt xs element minOccurs 0 name serviceSpecRole type xs string gt lt xs sequence gt lt xs complexType gt xs complexType name serviceType gt lt xs sequence gt lt xs element minOccurs 0 name type type xs string gt lt xs sequence gt lt xs complexType gt lt xs complexType name legacyServiceSpec gt lt xs complexContent gt xs extension base serviceSpec gt lt xs sequence gt lt xs element maxOccurs unbounded minOccurs 0 name nativeURIs nillable true type xs string gt lt xs sequence gt lt xs extension gt lt xs complexContent gt lt xs complexType gt lt xs complexType name deployableService gt lt xs complexContent gt xs
33. d label to NODE SELECTOR property on the ee properties file 38 CHAPTER 4 EXTENDING ENACTMENT ENGINE Chapter 5 Elasticity and QoS management As mentioned in Chapter 2 the Enactment Engine is able to modify a choreography that is currently running For instance one may decide to switch from using a service offered by one provider to a compatible service by a different provider or to increase decrease the number of deployed replicas of a given service in order to adapt to fluctuations in usage load To do this the user simply uses the API again to submit an updated version of the choreography specification to the Enactment Engine and requests the redeployment of the choreography The Enactment Engine in turn detects the modifications made to the choreography and performs the requested modifications by deploying new versions of services removing service replicas etc This capability together with the flexibility offered by the CHOReOS monitoring subsystem presents the user with the framework necessary to adjust the run time environment of the choreography according to QoS parameters and constraints such as response time or cost In order to accomplish this the user needs to create a separate daemon that acts both as a monitoring client and as a client for the Enactment Engine As a client for the monitoring system this daemon uploads rules to the Glimpse Monitoring CEP and awaits for notifications from it whenever such rules are
34. e tools to manage your VMs e The Enactment Engine creates VMs in the US East Amazon datacenter e The SSH keypairs are datacenter dependent Therefore if you create a keypair in the EU datacenter it won t be valid for your VMs 1 3 2 OpenStack OpenStack is an open source private cloud platform that provides services to retrieve VMs as you need in the same way that Amazon EC2 However you must install OpenStack in your own infrastructure 1 2 3 1 4 CHECKOUT AND COMPILATION 7 which means you must own at least a little cluster or a very powerful machine to host the created VMs Moreover the OpenStack installation and configuration is not a simple task Some hints e OpenStack does not provide public IPs therefore some VPN configuration is necessary to log into the provisioned nodes e You can also use the nova command line tool to manage your VMs e You need to host an Ubuntu Server 12 04 image within your OpenStack infrastructure You will use the ID of this image to configure Enactment Engine 1 3 3 Fixed cloud provider If you are learning how to use the Enactment Engine and want just to experiment it the FixedCloud Provider may be the most suitable option to you It is also useful if you want to use Enactment Engine with your own already existing cluster machines With it you are responsible to manually creating and setting virtual machines and telling to Enactment Engine which machines must be used by it This a
35. ent Engine clients access its features through the REST API that is described in this section Create a choreography HTTP Method URI Request body Responses 201 CREATED location chors id ChorSpec XML representation POST p HOTS ue Tasting 2d 400 BAD REQUEST 500 ERROR Creates a specification of the choreography on the Enactment Engine It does not deploy the chore ography Obs application xml is the value to the Content Type header when XML representations are written in the request or response body Retrieve choreography information HTTP Method URI Request body Responses 200 OK location chors id Body Choreography XML representation GET chors id 7 see Listing 2 2 400 BAD REQUEST 404 NOT FOUND 500 ERROR If this operation is invoked after the creation and before the deployment of a choreography the body response will be a Choreography representation without any deployed service Deploy a choreography HTTP Method URI Request body Responses 200 OK location chors id Body Choreography XML representation POST chors id deployment see Listing 2 2 400 BAD REQUEST 404 NOT FOUND 500 ERROR 3 00 18 CHAPTER 2 ENACTMENT ENGINE API With this invocation services will be finally deployed The response arrives only after the deployment of all services if no deployment fails
36. ent name ServiceNamespace type string gt lt element name ServiceName type string gt lt element name EndpointName type string gt lt sequence gt lt complexType gt lt complexType name Proxify Type gt lt sequence gt lt element name Url string gt lt element name Wsdl string gt lt sequence gt lt complexType gt lt schema gt The Listing 3 7 shows an example of config xml file that makes the deployment of a coordination delegate in a scenario where the correspondent business service is already running and available The Indeed the main scenario envisioned by CHOReOS is that there are already a lot of the services running on the wild 30 CHAPTER 3 HOW TO PACKAGE SERVICES weatherforecastservice lts and cdweatherforecastservice wsdl files referenced in lines 8 and 9 are provided within the tar gz package The use of the in these lines is mandatory The url http 192 168 56 101 8192 weatherforecastservice provided in line 15 as well as the corre spondent WSDL indicated in line 15 are references to a service already running and accessible The ServiceNamespace line 20 is the targetNamespace defined in the service WSDL The value of the ServiceName element line 21 must correspond to the value of the name attribute of the service ele ment in the service WSDL
37. eographies are made just to compose these already running services situation in which only coordels are actually deployed 3 00 3 6 SOAP SERVICE TYPE 31 dependency name the name of the dependency that implements the role above It works as a label that the service may use to distinguish different available services playing the same role These different services are actually different implementations possibly belonging to different organizations dependency endpoints the list of alternative URIs to access the dependency It has several URIs because a service may has multiple instances to improve its scalability It is expected but not required from the dependent service to implement some load balancing between the different URIs However the dependent service may simply pick up anyone of the received endpoints URIs passed to the setInvocationAddress operation do not contain the wsdl suffix The expected interface of the setInvocationAddress operation is formally expressed by the WSDL elements presented in the Listing 3 9 Listing 3 9 Parts of the service WSDL that define the setInvocationAddress operation lt xs schema version 1 0 targetNamespace http services choreos org gt xs complexType name setInvocationAddress gt lt xs sequence gt lt xs element name arg0 type xs string minOccurs 0 gt lt xs element name argl ty
38. epresentations we use here the UML notation since it makes easier to the reader to understand the concepts We proceed with a brief explanation about each class ChoreographySpec represents what the middleware needs to know to enact a choreography ServiceSpec a super class for common data of DeployableServiceSpec and LegacyServiceSpec LegacyServiceSpec represents an already existing service to used by the choreography DeployableServiceSpec represents what the middleware needs to know to deploy a service with one or more instances for load balancing ServiceDependency represents dependencies among services if service A invokes service we say service A depends on service B Choreography provides information about a choreography instance Service a super class for common data of DeployableService and LegacyService LegacyService provides information about a legacy service DeployableService provides information about a deployed service ServiceInstance provides information about a specific instance also called replica of a deployed service URI node data etc LegacyServiceInstance provides information about a specific instance of a legacy service Node information about the node including IP address where a service instance is running 1Deployer is the human operator responsible by the deployment process 11 12 ServiceSpec name String serviceType ServiceType roles List lt String gt
39. ere the key is the name of the new service type and the value is the full qualified name of the ContextSender implementing class It is also necessary to recompile the EnactmentEngine project in such way it can access the implementing class Now you can create new service specs using the just created service type But be sure services implementation are prepared to receive the set InvocationAddress invocation 4 5 Supporting new node selection policies A node selection policy defines the mapping of services to cloud nodes Since cloud nodes are dynamically created node selection policies must be flexible and not rely on hard coded IPs A node selection policy may define nodes to be used based on services non functional properties To create a new node selector you must create a new NodeSelector Listing 4 5 implementation Pay attention that such implementation must be thread safe since multiple threads will invoke concurrently the method select Listing 4 5 NodeSelector interface public interface NodeSelector extends Selector lt CloudNode DeployableServiceSpec gt public interface Selector lt T R gt public List lt T gt select R requirements int objectsQuantity throws NotSelectedException After writing the new node selector you must associate this selector to a label by editing the extensible node selector properties file at EnactmentEngine resources folder To use the new se lector finally you must attribute the define
40. extension base service gt lt xs sequence gt lt xs element maxOccurs unbounded minOccurs 0 name selectedNodes nillable true type cloudNode gt lt xs element maxOccurs unbounded minOccurs 0 name serviceInstances nillable true type serviceInstance gt lt xs sequence gt lt xs extension gt 191 192 193 194 195 196 197 198 199 200 201 202 208 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 2 5 CHOREOGRAPHY XML SCHEMA DEFINITION XSD FILE 23 lt xs complexContent gt lt xs complexType gt xs complexType abstract true name service gt lt xs sequence gt lt xs element minOccurs 0 name spec type serviceSpec gt lt xs element minOccurs 0 name UUID type xs string gt lt xs sequence gt lt xs complexType gt lt xs complexType name cloudNode gt lt xs sequence gt XS i e 1 lt xs element 0 name cpus type xs int gt lt xs element minOccurs 0 name hostname type xs string gt XS i i xs 1 lt xs element minOccurs 0 name id type xs string gt XS i i xs 1 lt xs element minOccurs 0 name image type xs string
41. f the depen dency matching the name attribute and the the role provided by the dependency 2 DeployableServiceSpec packageUri the location of the binary file to be deployed packageType the type of the deployable package according to the PackageType enumeration endpointName the endpoint suffix after deployment For example if the service will be deployed as http lt some_ip gt choreos service the endpoint name is choreos service Note that multiple replicas of a single service will all use the same endpoint port the TCP port used by the service Note that multiple replicas of a single service will all use the same port Mandatory if type is COMMAND LINE owner must match a cloud account name configured on EE It will define under which cloud infrastructure the service will be deployed numberOfInstances How many instances of the service should be deployed onto different virtual machines in order to allow the load to be distributed version the service version which is used by the Enactment Engine to define which services must be redeployed in a choreography update not used currently resourcelmpact General information regarding the expected type of machine needed to run the service see Resource impact specification 3 LegacyServiceSpec URIs The URIs for the various replicas of the service More about dependencies In a service composition some services depends on other services A service that depends
42. g xml file must be built according to the schema in the Listing 3 6 Configuration is the root element Service is an element containing a set of Actions made on a particular EasyESB node These actions can be Deploy deploys an artifact in EasyESB BPEL CD etc It must contain the MainResource element and can have additional Resource elements Bind binds a running web service onto an EasyESB this action receives as parameter the web service URL and the web service WSDL location Proxify binds a running web service onto an EasyESB node and re export it using the same parameters used in the Bind action Expose exposes an EasyESB internal service as a web service Parameters are ServiceNamespace and ServiceName that correspond to the QName of the service defined in the WSDL usually it is the WSDL target namespace plus the name attribute of the service element 00 34 m 3 4 EASY ESB PACKAGE TYPE 29 Listing 3 6 config xml schema lt xml version 1 0 encoding UTF 8 gt schema targetNamespace http ebmwebsourcing com cli schema elementFormDefault qualified xmlns http www w3 org 2001 XMLSchema xmlns tns http ebmwebsourcing com cli schema gt element name Configuration type tns ConfigurationType gt lt complexType name ConfigurationType gt lt sequence gt lt element maxOccurs unbounded name Service type tns
43. gt lt packageType gt lt packageUri gt http valinhos ime usp br 54080 enact_test v3 Airline 3 0 0 jar packageUri gt lt port gt 1234 lt port gt resourceImpact gt lt version gt 0 1 lt version gt lt spec gt lt UUID gt 68 d8e82b f6e6 4314 9415 d2a18f61edcf lt UUID gt lt selectedNodes gt lt hostname gt choreos node lt hostname gt lt id gt 1 lt id gt lt ip gt 192 168 56 101 lt ip gt lt selectedNodes gt lt servicelnstances gt lt instanceld gt airline0 lt instanceld gt lt nativeUri gt http 192 168 56 101 1234 airline lt nativeUri gt lt node gt lt hostname gt choreos node lt hostname gt lt id gt 1 lt id gt lt ip gt 192 168 56 101 lt ip gt lt node gt lt serviceSpec gt lt name gt airline lt name gt lt roles gt airline lt roles gt lt serviceType gt lt type gt SOAP lt type gt lt serviceType gt lt endpointName gt airline lt endpointName gt lt numberOflInstances gt 1 lt numberOflInstances gt lt packageType gt lt type gt COMMANDLINE lt type gt lt packageType gt lt packageUri gt http valinhos ime usp br 54080 enact_test v3 Airline 3 0 0 jar lt packageUri gt lt port gt 1234 lt port gt lt resourcelmpact gt lt version gt 0 1 lt version gt lt serviceSpec gt lt serviceInstances gt lt deployableServices gt lt id gt 1 lt id gt 2 3 REST API 17 147 lt choreography gt 2 3 REST API The Enactm
44. gt airline lt endpointName gt numberOfInstances 1 numberOfInstances lt packageType gt ty pe COMMAND LINEc t y pe lt packageType gt lt packageUri gt http valinhos ime usp br 54080 enact_test v3 Airline 3 0 0 jar lt packageUri gt lt port gt 1234 lt port gt lt resourceImpact gt lt version gt 0 1 lt version gt lt deployableServiceSpecs gt lt deployableServiceSpecs gt lt dependencies gt lt serviceSpecName gt airline lt serviceSpecName gt lt serviceSpecRole gt airline lt serviceSpecRole gt lt dependencies gt lt name gt travelagency lt name gt lt roles gt travelagency lt roles gt lt serviceType gt lt type gt SOAP lt type gt lt serviceType gt lt endpointName gt travelagency lt endpointName gt numberOfInstances 1 numberOfInstances packageType ty pe COMMAND LINE lt t y pe lt packageType gt lt packageUri gt http valinhos ime usp br 54080 enact_test v3 TravelAgency 3 0 0 jar lt packageUri gt lt port gt 1235 lt port gt resourceImpact gt lt version gt 0 1 lt version gt lt deployableServiceSpecs gt lt choreographySpec gt Listing 2 2 Choreography XML representation example lt choreography gt lt choreographySpec gt lt deployableServiceSpecs gt lt name gt airline lt name gt lt roles gt airline lt roles gt lt serviceType gt lt type gt SOAP lt type gt lt serviceType gt Java Architecture for
45. he middleware assumes the port as 8080 the Tomcat default port If the endpoint name is not specified it is assumed as the WAR file name without the war extension as it is the default behavior in Tomcat Dependencies JAR libraries must be packaged within the WAR file However we provide a set of libraries in our Tomcat installation that are usually used in Java projects specially projects using the JAX WS framework If some of these JARs are used by your service they are not required to be packaged within your WAR file since they are already on the Tomcat class path This strategy helps in decreasing the size of WAR files and therefore decreasing the deployment time The provided libraries are the following e activation 1 1 jar e ecj 3 7 1 jar 3 3 TOMCAT PACKAGE TYPE gmbal api only 3 1 0 b001 jar ha api 3 1 8 jar istack commons runtime 2 2 1 jar javax annotation 3 1 1 b06 jar jaxb api 2 2 3 jar jaxb impl 2 2 4 1 jar jaxws api 2 2 5 jar jaxws rt 2 2 5 jar jsr 81 api 1 0 MR1 jar management api 3 0 0 b012 jar mimepull 1 6 jar policy 2 2 2 jar resolver 20050927 jar saaj api 1 3 3 jar saaj impl 1 3 10 jar stax api 1 0 2 jar stax api 1 0 1 jar stax ex 1 4 jar stax2 api 3 1 1 jar streambuffer 1 2 jar tomcat api jar tomcat jdbc jar tomcat util jar tomcat libs tar gz txw2 20090102 jar woodstox core asl 4 1 1 jar wstx asl 3 2 3 jar 27 One way to be sure that you are using the required versions is making
46. he service port address in the WSDL file see Listing 3 11 when seen from remote locations do not use localhost 0 0 0 0 or other unsuitable addresses as lan private IPs for example Remember the client that sees the WSDL needs an accessible endpoint Listing 3 11 Good example of service port address on a WSDL file lt service name AirlineServiceService gt port name AirlineServicePort binding tns AirlineServicePort Binding gt lt soap address location http 200 221 3 47 1234 airline gt lt port gt lt service gt If service A needs to invoke service B there is no problem if service A is compiled with classes used to build service B Actually usually it is very useful to A having access to B interfaces Nonetheless this class dependency must be only static There is no point in service A trying to access objects states of service B or access resources as configuration files bundled in service B package The packageUri attribute defines the URL from where the Enactment Engine retrieves the package to be deployed Therefore all the services packages need to be already Internet accessible at deployment time This can be accomplished for example by hosting the packages on a web server Packages cannot be downloaded from https URLs This restricts using some services such as Dropbox to host the packages 34 CHAPTER 3 HOW TO PACKAGE SERVICES m Chapter
47. ices datamodel uri package on the EnactmentEngineAPI project Hint if your package type is based on some kind of container to run the services such as Tomcat it may be a good idea to prepare a new image with this container already installed and running So you can configure EE to create VMs with an already running instance of your chosen container e g JBoss This strategy helps in achieving a faster deployment 00 4 m 44 SUPPORTING NEW SERVICE TYPES 37 4 4 Supporting new service types Although web services came to tackle the interoperability issue today we have a couple of technologies implementing the concept of services The main standards in this context are SOAP and REST but other technologies could be used to implement services such as JMS In the Enactment Engine context the service type affects only how the setInvocationAddress is invoked Therefore to support a new service type you have only to write a new ContextSender Listing 4 4 implementation Listing 4 4 ContextSender interface public interface ContextSender public void sendContext String serviceEndpoint String partnerRole String partnerName List lt String gt partnerEndpoints throws ContextNotSentException The final step is to edit the extensible context sender properties file located on EnactmentEngine resources folder You must add a line in the format SERVICE TYPE full qualified class name wh
48. ination Delegates CDs Although a coordination delegate proxifies all the operations of a SOAP service the proxified setInvocationAddress operation will be not invoked If a coordination delegate cdA is declared to depend on a coordination delegate cdB the Enactment Engine will link the EasyESB nodes hosting the coordination delegates by invoking the addNeighbour operation of the EasyESB hosting cdA passing as neighbor the EasyESB node hosting cdB Such operation enables coordination delegates to communicate directly among them by using the primitives UPDATE_STATE WAIT NOTIFY provided by the CD component running on EasyESB nodes Every CD depend on some business service SOAP service But this dependency must be not declared on the service specification It is a implicit dependency that must be declared on the config xml file of the correspondent CD Finally when some SOAP service is declared to depend on some CD the SOAP service will receive through setInvocationAddress the CD endpoint exposed by the bus Such CD endpoint proxifies the service related to the CD 3 8 Coding guidelines Here are just some few important reminders e Do not forget to unblock the TCP ports used by your services Often this may be accomplished by the usage of management tools of your cloud environment e WAR packages are preferable to JAR packages WAR packages avoid port conflict issues and it is easier to manage the life cycle of services distributed in W
49. ly supported by the Enactment Engine This chapter is targeted to service developers that intend to develop EE compatible services De scriptions and hints encompass coding and packaging phases This guide considers only the service and package types currently supported by EE 3 2 COMMAND LINE package type Services whose package type are specified as COMMAND LINE must be provided as JAR packages The JAR must contain all the dependencies and resources within it When using this package type it is mandatory to fill the attributes port and endpointName on DeployableServiceSpec It must be possible to run the JAR by typing the command java jar file name where file name gt must be replaced with the name of the JAR file Every JAR file contains a file called MANIFEST MF within the META INF folder which is in the root of JAR file A runnable JAR contains the following entry in its MANIFEST file Main Class lt class gt where class must be replaces by the full qualified name of the class containing the main method as for example org ow2 choreos AirlineStarter The Listing 3 1 provides an example of main class within a JAR file The Airline interface is the business interface and the AirlineService is the implementing class that uses the JAX WS framework to expose SOAP services In this example the used TCP port and the endpoint name are defined in the SERVICE ADDRESS assignment line 7 The used port is the 1234 and the endpoint n
50. nactment Engine to each specific recipe You can have an idea about how to use them by looking to the WAR cookbook implementation in Listing 4 2 and Listing 4 3 After writing the new recipe you must associate this recipe to the new package type by editing the extending cookbooks properties file Listing 4 2 Recipe template for WAR deployment include_recipe apt include recipe tomcat 007608 remote file war file do source node CHOReOSData serviceData NAME PackageURL path 3212006 tomcat webapp dir NAME war mode 0755 action create if missing end file Z node tomcat webapp dir NAME war do action nothing end Listing 4 3 Attributes template for WAR deployment default CHOReOSData serviceData NAME PackageURL PACKAGE URL It is up to EE to guess the service URI too A service URI follows the format http IP PORT CONTEXT And the CONTEXT formation rule is package type dependent Therefore when extending package type it is necessary to create a new URIContextRetriever implementation and to link this implementation to its package type in the URIContextRetrieverFactory class To make this relationship it is enough to add a single line in the factory by adding a new entry in the classMap variable Both URIContextRetriever and URIContextRetrieverFactory classes are in the org ow2 choreos serv
51. nbounded minOccurs 0 name nativeURIs nillable true type xs string lt xs sequence gt lt xs extension gt lt xs complexContent gt lt xs complexType gt lt xs simpleType name memoryType gt lt xs restriction base xs string gt xs enumeration value SMALL gt xs enumeration value MEDIUM gt xs enumeration value LARGE gt lt xs restriction gt lt xs simpleType gt lt xs schema gt Choreography XSD lt xml version 1 0 encoding UTF 8 gt lt xs schema xmlns xs http www w3 org 2001 XMLSchema version 1 0 lt lt xs element name choreography type choreography gt lt xs element name choreographySpec type choreographySpec gt lt xs element name cloudNode type cloudNode gt lt xs element name deployableService type deployableService gt lt xs element name deployableServiceSpec type deployableServiceS pec gt lt xs element name legacyServiceSpec type legacyServiceSpec gt lt xs element name resourcelmpact type resourceImpact gt lt xs complexType name choreography gt lt xs sequence gt lt xs element minOccurs 0 ref choreographySpec gt lt xs element maxOccurs unbounded minOccurs 0 name deployableServices nillable true type deployableService gt lt xs element minOccurs 0 name id type xs
52. ng 2 5 Example of choreography specification using the Java API public class ChorSpecExample static final static static http static http static static public public public String AIRLINE airline final String TRAVEL AGENCY travelagency final String AIRLINE valinhos ime usp br 54080 airline jar final String TRAVEL AGENCY JAR valinhos ime usp br 54080 travel jar final int AIRLINE PORT 1234 final int TRAVEL AGENCY PORT 1235 public public public private ChoreographySpec chorSpec private DeployableServiceSpec airlineSpec private DeployableServiceSpec travelSpec public ChoreographySpec getChorSpec createAirlineSpec createTravelAgencySpec chorSpec new ChoreographySpec this airlineSpec return chorSpec this travelSpec private void createAirlineSpec airlineSpec airlineSpec airlineSpec airlineSpec airlineSpec airlineSpec airlineSpec airlineSpe new DeployableServiceSpec setName AIRLINE setServiceType ServiceType SOAP set PackageType PackageType COMMANDLINE set PackageUri AIRLINE JAR set Port AIRLINE PORT setEndpointName AIRLINE c setRoles Collections singletonList AIRLINE private void createTravelAgencySpec travelSpec travelSpec travelSpec travelSpec travelSpec travelSpec travelSpec travelSpec ServiceDep new DeployableServiceSpec
53. nterface package org ow2 choreos chors import org ow2 choreos chors datamodel Choreography import org ow2 choreos chors datamodel ChoreographySpec public interface EnactmentEngine public String createChoreography ChoreographySpec chor public Choreography getChoreography String chorld throws ChoreographyNotFoundException public Choreography deployChoreography String chorld throws DeploymentException ChoreographyNotFoundException public void updateChoreography String 60110 ChoreographySpec spec throws EnactmentException ChoreographyNotFoundException To use the Enactment Engine Java client in your code it s enough to import the API project into your project One way of doing this is using Maven install the API project into your local maven repo EnactmentEngineAPI mvn install add it as a dependency of your project by editing your pom xml Listing 2 4 and finally compile your project 3 m 2 4 JAVA CLIENT 19 Listing 2 4 Adding EnactmentEngineAPI as a dependency of your project lt dependency gt lt groupld gt org ow2 choreos lt groupld gt lt artifactId gt EnactmentEngineAPI lt artifactId gt lt version gt 0 0 1 SNAPSHOT lt version gt lt dependency gt The Listing 2 5 shows an example of how to use the Java API to create a choreography specification This example is equivalent to the XML in Listing 2 1 Listi
54. pe xs string minOccurs 0 gt lt xs element maxOccurs unbounded minOccurs 0 name arg2 type xs string gt lt xs sequence gt lt xs complexType gt lt xs complexType name setInvocationAddressResponse gt lt xs sequence lt lt xs complexType gt lt xs schema gt message name setInvocationAddress gt part name parameters element tns setInvocationAddress gt lt message gt message name setInvocationAddressResponse gt part name parameters element tns setInvocationAddressResponse gt lt message gt lt portType gt operation name setInvocationAddress gt lt input message tns setInvocationAddress gt output message tns setInvocationAddressResponse gt lt operation gt lt portType gt If you are using the JAX WS framework you can easily create a compatible setInvocationAddress operation by using the code provided in the Listing 3 10 n d 00 0 Hm 32 CHAPTER 3 HOW TO PACKAGE SERVICES Listing 3 10 Implementing setInvocationAddress with JAX WS WebService public class SomeWebServiceClass WebMethod public void setInvocationAddress String role String name List lt String gt endpoints 3 7 COORDEL service type This service type must be used when declaring service specifications to CHOReOS Coord
55. re than 5 of requests during the last 2 minutes have a response time above 120 miliseconds new replicas of the service should be created the class AddReplica should be run 39 40 CHAPTER 5 ELASTICITY QOS MANAGEMENT when ev ResponseTimeEvent over window time 2m Number eventSum doubleValue from accumulate event ResponseTimeEvent ev service service ev chor chor ev ip ip over window time 2m count event Number intValue gt eventSum 0 05 from accumulate sEvent ResponseTimeEvent value gt 120 ev service service ev chor chor ev ip ip over window time 2m count sEvent then ResponseDispatcher NotifyMeValue AddReplica eeConsumer String ev ip String ev service end Finally the AddReplica class then interacts with the Enactment Engine to update the number of replicas of the service public void handleEvent HandlingEvent event List lt DeployableService gt services registryHelper getServicesHostedOn event getNode List lt DeployableServiceSpec gt serviceSpecs registryHelper getServiceSpecsForServices services Choreography c registryHelper getChor event getNode ChoreographySpec cSpec c getChoreographySpec for DeployableServiceSpec spec serviceSpecs for DeployableServiceSpec 8 cSpec getDeployableServiceSpecs if s getName equals spec getName s setNumberOfInstances s getNumberOfInstances 1
56. ript It can take several minutes Internet access is necessary during compilation 1 5 Configuration Open the folder EnactmentEngine src main resources and create a ee properties file by copying the ee properties template file The new properties file must be created in the same folder Open the just created properties file and edit it following instructions on the template file The Listing 1 2 shows an example Do the same to the clouds properties template file in the clouds properties file you will define configuration to access your infrastructure provider Listing 1 1 ee properties example EE PORT 9102 Value must be a cloud account name in clouds properties 1Obs do not use a key with password 8 CHAPTER 1 INSTALLATION GUIDE DEFAULT_CLOUD_ACCOUNT My AWs_ACCOUNT Values in node selector properties NODE SELECTOR LIMITED ROUND ROBIN Maximum number of VMs that be created set if using NODESELECTOR LIMITED ROUND ROBIN VM_LIMIT 10 Creates a reservoir of extra VMs to make the deployment faster and more scalable The trade off is the cost of some more VMs If the pool size reaches the threshold the pool size is increased by one To not increase your pool size set threshold as negative or greater than the initial pool size RESERVOIR true RESERVOIR_INITIAL_SIZE 5 RESERVOIR THRESHOLD 1 Listing 1 2 cloud properties example MY_CLUSTER CLOUD PROVIDER FIXED CLUSTER FIXED V
57. string gt lt xs element maxOccurs unbounded 0 name legacyServices nillable true type legacyService gt lt xs sequence gt lt xs complexType gt lt xs complexType name choreographySpec gt lt xs sequence gt lt xs element maxOccurs unbounded minOccurs 0 name deployableServiceS pecs nillable true type deployableServiceSpec gt lt xs element maxOccurs unbounded minOccurs 0 name legacyServiceSpecs nillable true type legacyServiceSpec gt lt xs sequence gt lt xs complexType gt lt xs complexType name deployableServiceSpec gt lt xs complexContent gt xs extension base serviceSpec gt lt xs sequence gt lt xs element minOccurs 0 name cloudAccount type xs string gt lt xs element minOccurs 0 name desiredQoS type desiredQoS gt lt xs element minOccurs 0 name endpointName type xs string gt lt xs element name numberOflnstances type xs int gt lt xs element minOccurs 0 name packageType type packageType gt lt xs element minOccurs 0 name packageUri type xs string 124 125 126 127 128 129 130 131 132 133 134 135 136 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 18
58. voids the overhead of dealing with a cloud environment When creating a virtual machine to be used by the Enactment Engine be sure e to use the Ubuntu 12 04 as operating system e it is possible to SSH into the node without typing a password http www integrade org br ssh without password e use sudo in the machine without typing a password type sudo visudo and add the line user ALL NOPASSWD ALL at the end change user by the actual user e to synchronize the machine clock ntpdate ccsl ime usp br To verify if your VM was properly set you may run the org ow2 choreos deployment nodes cloudprovider FixedConnection Test test The Enactment Engine will not take care of bootstrapping installing Chef on your machines since this process is taken only when creating new machines You must bootstrap your machines by running the org ow2 choreos deployment nodes cm BootstrapFixedMachines class When you run the Bootstrap FixedMachines class Enactment Engine will bootstrap the configured fixed machines We will talk about configuration soon Depending on how you create your VMs some network configuration may be needed In case of using VirtualBox you can refer to http ccsl ime usp br foswiki bin view Choreos VMs 1 4 Checkout and Compilation To checkout the code git clone https github com choreos enactment_engine git After installing Maven 3 open the terminal at the enactment_engine folder and run the build sh sc
59. xisting keys on the same file and the value is the full qualified name of the CloudProvider implementing class It is also necessary to recompile the EnactmentEngine project in such way it can access the implementing class One suggestion is by adding your class in your local maven repository and edit the EnactmentEngine project s pom to make EnactmentEngine dependent on your project holding the new cloud provider Finally to use your new cloud provider it is necessary to configure the clouds properties adding a cloud account whose CLOUD PROVIDER property values the NAME defined in the cloud_providers properties file 4 3 Supporting new package types Services may be delivered in different package types such as JARs WARs etc Each package type has its own specific deployment procedures as well its specific process to start the service When using different technologies such as Python to write new services you will need to define a new package type as well the deployment procedure associated with it Such procedure is specified in Chef recipe So the first step is to create a new Chef cookbook similar to the jar and war recipes already provided by Enactment Engine These cookbooks are actually templates that EE will use to create specific cookbooks to each service to be deployed You can use the the constants SPACKAGE URL and NAME within your cookbook recipe and attributes files These constants will be injected by E
60. xs schema xmlns xs http www w3 org 2001 XMLSchema version 1 0 lt lt xs element name choreographySpec type choreographySpec gt lt xs element name deployableServiceSpec type deployableServiceS pec gt lt xs element name legacyServiceSpec type legacyServiceSpec gt lt xs element name resourcelmpact type resourcelmpact gt xs complexType name choreographySpec gt lt xs sequence gt lt xs element maxOccurs unbounded 0 name deployableServiceS pecs nillable true type deployableServiceS pec gt lt xs element maxOccurs unbounded minOccurs 0 name legacyServiceSpecs nillable true type legacyServiceSpec gt lt xs sequence gt lt xs complexType gt lt xs complexType name deployableServiceSpec gt lt xs complexContent gt xs extension base serviceSpec gt lt xs sequence gt lt xs element minOccurs 0 name cloudAccount type xs string gt lt xs element minOccurs 0 name desiredQoS type desiredQoS gt lt xs element minOccurs 0 name endpointName type xs string gt lt xs element name numberOfInstances type xs int gt lt xs element minOccurs 0 name packageType type packageType gt lt xs element minOccurs 0 name packageUri type xs string gt lt xs element name port
61. your project depending on JAX WS by adding the fragment of Listing 3 3 in your Maven s pom Listing 3 3 Making your project depending on JAX WS using Maven lt dependency gt lt groupld gt com sun xml ws lt groupld gt lt artifactId gt jaxws rt lt artifactId gt lt version gt 2 1 4 lt version gt lt dependency gt If you write your web service using JAX WS your WAR file must also package a sun jaxws xml file as Listing 3 4 As any other WAR file it must also contain a web xml file If your service was built with JAX WS your web xml file must be similar to the one presented in the Listing 3 5 Be aware that besides the usual definition of servlet and servelet mapping elements it is also necessary to declare the listener element exactly as in the example lines 8 9 and 10 1The instructions about the sun jaxws xml and web xml files were retrieved from http www mkyong com webservices jax ws deploy jax ws web services on tomcat 00 4 28 CHAPTER 3 HOW TO PACKAGE SERVICES Listing 3 4 Example of sun jaxws xml file lt xml version 1 0 encoding UTF 8 gt endpoints xmlns http java sun com xml ns jax ws ri runtime version 2 0 gt lt endpoint name Airline implementation org ow2 choreos AirlineService url pattern airline gt lt endpoints gt
Download Pdf Manuals
Related Search