From overlord-commits at lists.jboss.org Thu Oct 9 06:59:42 2008 Content-Type: multipart/mixed; boundary="===============3075746994745943392==" MIME-Version: 1.0 From: overlord-commits at lists.jboss.org To: overlord-commits at lists.jboss.org Subject: [overlord-commits] Overlord SVN: r373 - in cdl/trunk/docs/docbook: samplesguide/src/main/module and 1 other directories. Date: Thu, 09 Oct 2008 06:59:42 -0400 Message-ID: --===============3075746994745943392== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: objectiser Date: 2008-10-09 06:59:41 -0400 (Thu, 09 Oct 2008) New Revision: 373 Added: cdl/trunk/docs/docbook/samplesguide/src/main/module/cdlconformance.xml cdl/trunk/docs/docbook/samplesguide/src/main/module/cdlvalidator.xml Modified: cdl/trunk/docs/docbook/samplesguide/src/main/master.xml cdl/trunk/docs/docbook/samplesguide/src/main/module/overview.xml cdl/trunk/docs/docbook/userguide/src/main/module/conversation-aware-esb.= xml Log: Converted samples guide into docbook format. Modified: cdl/trunk/docs/docbook/samplesguide/src/main/master.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- cdl/trunk/docs/docbook/samplesguide/src/main/master.xml 2008-10-09 08:1= 5:52 UTC (rev 372) +++ cdl/trunk/docs/docbook/samplesguide/src/main/master.xml 2008-10-09 10:5= 9:41 UTC (rev 373) @@ -12,5 +12,7 @@ = + + = Added: cdl/trunk/docs/docbook/samplesguide/src/main/module/cdlconformance.x= ml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- cdl/trunk/docs/docbook/samplesguide/src/main/module/cdlconformance.xml = (rev 0) +++ cdl/trunk/docs/docbook/samplesguide/src/main/module/cdlconformance.xml = 2008-10-09 10:59:41 UTC (rev 373) @@ -0,0 +1,226 @@ + + + + CDL Conformance + + +There are two examples to demonstrate the conversation aware ESB actions, = and the conformance checking against a choreography. These are pu= rchasing, a simple customer/supplier example, and brok= erage which extends the purchasing example through the introduct= ion of a broker that mediates between potentially multiple suppliers to fin= d the best deal. + + +The other relevant folders for these examples are, common which contains the service implementation of the 'Credit Agency' which= is used by both examples, and client which contains c= lient applications to test both examples. + + +
+ Purchasing Example + + +The purchasing example describes the interactions between a Buyer, Store a= nd Credit Agency. The flow for this example would be: + + + +Buyer send a 'buy' request to Store + + +Store send a 'credit check' request to the Credit Agency. + + +If the Credit Agency returns a successful message, then the Store will sen= d a 'BuyConfirmed' to user. + + +If the Credit Agency returns a failed message, then the Store will send a = 'BuyFailed' to user. + + + + +To check conformance, we need to import the model and service implementati= on projects into the Eclipse environment. This is achieved by: + + + +Select the 'Import...' menu item, associated with the context menu on the = background of the left panal (Navigator or Package depending on perspective= being viewed). When the import dialog appears, select the General->Existin= gProject from Workspace option and press the 'Next' button. + + +Ensuring that the 'Select root directory' radio button is selected, press = the 'Browse' button and navigate to the samples/purchasing/models= folder, press 'Ok' and then press 'Finish'. + + +Then repeat steps (1) and (2) for the following project folders: + + + samples/purchasing/store + + + samples/common/creditAgency + + + + + +The purchasing-models project contains the CDL used t= o perform conformance checking on the src/main/resources/META-INF= /jboss-esb.xml files within the other projects. A full explanati= on of the conversation aware ESB actions can be found in the Conv= ersational Aware ESB section of the User Guide in the docs folder. + + +To provide a simple demonstration of the conformance checking: + + + +Double click on purchasing-store/src/main/resources/META-INF/jbo= ss-esb.xml + + +Scroll down to the second action, within the first service. This represent= s a ReceiveMessageAction and has a property defining t= he message type to be received. + + +Edit the 'messageType' property value, e.g. by adding an 'X' to the end of= the value. + + +Then save the file. This should result in an error being generated, compla= ining about a type mismatch. + + + +The information regarding the expected message type is obtained from the c= horeography description in the purchasing-models proje= ct. To identify the precise interaction within the choreography that this e= rror relates to, select the context menu associated with the error and choo= se the Quick Fix menu item. This will display a dialog with a list of fixes= , select the Show referenced description option and pr= ess OK. This will cause the relevant interaction within the choreography de= scription to be displayed. + + +Another Quick Fix option associated with this error is Update fr= om Referenced Description. By selecting this option, you will no= tice that the message type is changed back to the value without the 'X'. + + +
+ Running the Example + + + + First step is to install the ESB services. In a command window, + + + Go to the $Overlord/samples/purchasing/store folde= r and execute ant deploy + + + Go to the $Overlord/samples/common/creditAgency folder and execute ant deploy + + + + + Go to the $Overlord/samples/client folder and execu= te ant runPurchasingClient, which will s= end a 'BuyRequest' message to the Store, which will then perform the credit= check before returning a response to the client. + + + + +To see a different response from the client, change the isCredit= Valid method on the CreditAgencyPurchase cl= ass, within the common/creditAgency ESB service implem= entation, and then re-deploy the Credit Agency service. Then when the clien= t is re-run, a 'BuyFailed' message will be returned. + + +
+ +
+ +
+ Brokerage Example + + +The brokerage example describes the interactions between a Customer, Broke= r, Supplier and Credit Agency. The flow for this example would be: + + + + +Customer sends an 'enquiry' request to Broker + + +Broker sends the request to one or more Suppliers concurrently + + +When all of the quote responses have been received, or a timeout expires, = the available information is returned to the Customer + + +Customer decides whether to: + + + Cancel the transaction, or + + + Send a 'buy' request to the Broker + + + + +If a 'buy' request is received by the Broker, it will send a 'credit check= ' request to the Credit Agency + + +If the Credit Agency returns a successful message, then the Broker sends a= 'buy' request to the Supplier selected by the Customer (in the 'buy' reque= st), followed by a confirmation back to the Customer + + +If the Credit Agency returns a failed message, then the Broker will inform= the Customer + + + + +To check conformance, we need to import the model and service implementati= on projects into the Eclipse environment. This is achieved by: + + + +Select the 'Import...' menu item, associated with the context menu on the = background of the left panal (Navigator or Package depending on perspective= being viewed). When the import dialog appears, select the Genera= l->ExistingProject from Workspace option and press the 'Next' bu= tton. + + +Ensuring that the 'Select root directory' radio button is selected, press = the 'Browse' button and navigate to the samples/brokerage/models<= /emphasis> folder, press 'Ok' and then press 'Finish'. + + +Then repeat steps (1) and (2) for the following project folders: + + + samples/brokerage/broker + + + samples/brokerage/supplier + + + samples/common/creditAgency (if not already impor= ted for the previous example) + + + + + +The brokerage-models project contains the CDL used to= perform conformance checking on the src/main/resources/META-INF/= jboss-esb.xml files within the other brokerage projects. A full = explanation of the conversation aware ESB actions can be found in the Conversational Aware ESB section of the User Guid= e in the docs folder. + + +To provide a simple demonstration of the conformance checking: + + + +Double click on brokerage-broker/src/main/resources/META-INF/jbo= ss-esb.xml + + +Scroll down to the second action, within the first service. This represent= s a ReceiveMessageAction and has a property defining t= he message type to be received. + + +Edit the 'messageType' property value, e.g. by adding an 'X' to the end of= the value. + + +Then save the file. This should result in an error being generated, compla= ining about a type mismatch. + + + +The information regarding the expected message type is obtained from the c= horeography description in the brokerage-models projec= t. To identify the precise interaction within the choreography that this er= ror relates to, select the context menu associated with the error and choos= e the Quick Fix menu item. This will display a dialog with a list of fixes,= select the Show referenced description option and pre= ss OK. This will cause the relevant interaction within the choreography des= cription to be displayed. + + +
+ Running the Example + + + + First step is to install the ESB services. In a command window, + + + Go to the $Overlord/samples/brokerage/supplier fo= lder and execute ant deploy + + + Go to the $Overlord/samples/brokerage/broker fold= er and execute ant deploy + + + Go to the $Overlord/samples/common/creditAgency f= older and execute ant deploy + + + + + Go to the $Overlord/samples/client folder and exec= ute ant runBrokerageClient, which will i= nitially send an 'enquiry' message to the Broker, which will communicate wi= th the set of Suppliers to obtain the best quote. The client will then send= a 'buy' request, which will result in the Broker performing a credit check= before returning a response to the client. + + +
+ +
+ + Added: cdl/trunk/docs/docbook/samplesguide/src/main/module/cdlvalidator.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- cdl/trunk/docs/docbook/samplesguide/src/main/module/cdlvalidator.xml = (rev 0) +++ cdl/trunk/docs/docbook/samplesguide/src/main/module/cdlvalidator.xml 20= 08-10-09 10:59:41 UTC (rev 373) @@ -0,0 +1,100 @@ + + + + CDL Validator + +
+ Trailblazer Example + + +This example can be found in the trailblazer folder, = which contains an enhanced version of the trailblazer example found in the = JBossESB distribution. The main changes are the introduction of a File Base= d Bank, and modifications to the message structures to enable a consistent = conversation id to be carried with the messages. + + + + +Update the $JbossAS/server/default/deploy/jbossesb.sar/jbossesb-= properties.xml file, in the section entitled "transports" and sp= ecify all of the SMTP mail server settings for your environment. + + +Select the 'Import...' menu item, associated with the context menu on the = background of the left panal (Navigator or Package depending on perspective= being viewed). When the import dialog appears, select the Genera= l->ExistingProject from Workspace option and press the 'Next' bu= tton. + + +Ensuring that the 'Select root directory' radio button is selected, press = the 'Browse' button and navigate to the samples/trailblazer/model= s folder, press 'Ok' and then press 'Finish'. + + + +Once the models project has been installed, you can open the choreography = for the trailblazer (trailblazer.cdm) and also a scenario representing a va= lid transaction associated with the choreography (LoanRequest.scn). In the = choreography description editor, view the "Choreography Flows" tab to see t= he structure of the process. + + +To simulate the scenario against the choreography, to ensure that the chor= eography correctly caters for the valid business scenario, the user should = press the green 'play' button in the toolbar, associated with the Scenario = Editor. + + + + +Update the trailblazer/trailblazer.properties + +Update the file.bank.monitored.directory and file.output.directory properties. These are folders used by th= e File Based Bank, and are set to /tmp/input and /tmp/output by default. + + + +Update the trailblazer/esb/conf/jboss-esb.xml + +There is a fs-provider block, update the di= rectory attribute value to be the same as the file.out= put.directory value in trailblazer.properties file. + + + +Start the JBossAS server + + +From the trailblazer folder, execute the command to s= tart the ESB: ant deploy + +this should deploy the ESB and WAR files to your JBoss AS server= /default. + + + +From the trailblazer/banks folder, execute the comman= d to start the JMS Bank service: ant runJMSBank. + + +From the trailblazer/banks folder, execute the comman= d to start the JMS Bank service: ant runFileBank. + + +In the Eclipse environment, select the context menu associated with the trailblazer.cdm file, and choose the Choreogra= phy->Monitor menu item. Wait for the monitor window to start, an= d indicate that the choreography is being monitored, shown in the status li= ne at the bottom of the window. + + +Start a browser and enter the URL: localhost:8080/trailblazer. + + +Now you can submit quotes, You will see either a loan request rejected (si= ngle email) because the score is less than 4, or two emails (one from JMS b= ank and one from FileBased bank) with valid quotes. When entering subsequen= t quotes, make sure that the quote reference is updated, so that each sessi= on has a unique id. + + + +To demonstrate what occurs when the implementation deviates from the expec= ted behaviour as defined in the choreography description, try the following= steps: + + + +Edit the LoanBroker.java in the $Overlord/samples/trailblazer/cl= ient/src/org/jboss/soa/esb/samples/trailblazer/loanbroker folder + + +Find the following code within the processLoanRequest= method, and change the 4 to a 7 + + + //step 2 - check if score is acceptable + = + if (score >=3D 4) { + + + +Re-deploy the trailblazer example (step 7 above) + + +Issue further loan requests, remembering to change the quote reference eac= h time, until a Credit Check result of between 4 and 6 inclusive occurs, wh= ich will result in an out of sequence message being reported (in red) to th= e Choreography Monitor + + +It is currently a requirement that the choreography used within the Choreo= graphy Monitor is the same as the description used to locally monitor the s= ervices (i.e. within the overlord-cdl-validator.esb/models directory). + + + + +
+ = + Modified: cdl/trunk/docs/docbook/samplesguide/src/main/module/overview.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- cdl/trunk/docs/docbook/samplesguide/src/main/module/overview.xml 2008-1= 0-09 08:15:52 UTC (rev 372) +++ cdl/trunk/docs/docbook/samplesguide/src/main/module/overview.xml 2008-1= 0-09 10:59:41 UTC (rev 373) @@ -1,30 +1,30 @@ - - - - Overview - The Overlord CDL distribution contains two main types of functiona= lity: - - - the ability to validate executing services against a choreography desc= ription (an example of runtime governance). - - - the ability to build an ESB using 'conversation aware' actions which c= an be checked for conformance against a choreography description (an exampl= e of design time governance). - - = - = - - This document will describe the samples available to demonstrate each as= pect of the functionality. - - - Further information about configuring the runtime validation of services= against a choreography can be found in the UserGui= de. = - Information regarding the conversation aware ESB actions, and how to use= them in conjunction with conformance checking against a choreography descr= iption, can also be found in the UserGuide. - - = - - - Before attempting to install and run these examples, you must follow th= e instructions in the "Getting Started" Chapter of User Guide regarding installi= ng Overlord CDL into a JBossAS environment. - - - = - + + + + Overview + The Overlord CDL distribution contains two main types of functiona= lity: + + + the ability to validate executing services against a choreography desc= ription (an example of runtime governance). + + + the ability to build an ESB using 'conversation aware' actions which c= an be checked for conformance against a choreography description (an exampl= e of design time governance). + + = + = + + This document will describe the samples available to demonstrate each as= pect of the functionality. + + + Further information about configuring the runtime validation of services= against a choreography can be found in the UserGui= de. = + Information regarding the conversation aware ESB actions, and how to use= them in conjunction with conformance checking against a choreography descr= iption, can also be found in the UserGuide. + + = + + + Before attempting to install and run these examples, you must follow th= e instructions in the "Getting Started" Chapter of the User Guide regarding inst= alling Overlord CDL into a JBossAS environment. + + + = + Modified: cdl/trunk/docs/docbook/userguide/src/main/module/conversation-awa= re-esb.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- cdl/trunk/docs/docbook/userguide/src/main/module/conversation-aware-esb= .xml 2008-10-09 08:15:52 UTC (rev 372) +++ cdl/trunk/docs/docbook/userguide/src/main/module/conversation-aware-esb= .xml 2008-10-09 10:59:41 UTC (rev 373) @@ -165,13 +165,13 @@ The one or more 'messageType' elements, contained within the 'route' eleme= nt, defines the message type(s) that should be routed to the service descri= ptor associated with the 'route' element. - + If a route is marked as initiate=3D'true', with the c= orrect message type for an inbound message, but a service instance already = exists for the identity information extracted from the message, then the ro= ute will not be selected. The converse is also true. - + = - + Similarly, even if a message type match is found, if the service instance = is not in an appropriate state to invoke the target service descriptor, the= n the route will not be selected. - + If no routes are found for a particular inbound message, then an exception= will be reported. = @@ -740,9 +740,9 @@ The optional 'bindDetails' provides the means for the parent session to as= sign specific information from its state to the newly created pojo associat= ed with the child session. - + Currently the bound details from the parent will be copied into the child = pojo, and therefore modifications will not be reflected back into the paren= t pojo. - + The optional 'parentReference' is used to set a reference, on the child se= ssion's pojo, to the parent session's pojo. The value of the 'parentReferen= ce' identifies the property on the child session's pojo that will be used t= o reference the parent pojo. @@ -823,9 +823,9 @@ This error has an associated quick fix to enable the = missing activities to be inserted in the appropriate location within the ES= B configuration. = - + When this resolution is selected, if it displays an error Could not= insert activities found in referenced description, this means that= it was not possible to insert the additional activities automatically. - + =
@@ -838,9 +838,9 @@ This error has an associated quick fix to enable the = type to be updated in the relevant activity within the ESB configuration. = - + When this resolution is selected, if it displays an error Could not= update activity with information from referenced description, this= means that it was not possible to update the information automatically. - +
=
@@ -852,9 +852,9 @@ This error has an associated quick fix to enable the = unwanted activities to be removed from the ESB configuration. = - + When this resolution is selected, if it displays an error Could not= delete activities from the model, this means that it was not possi= ble to delete the activities automatically. - +
=
--===============3075746994745943392==--