pi4soa 2.0 Getting Started Guide

Transcription

1 pi4soa 2.0 Getting Started Guide by Gary Brown

2

3 1. Overview Installation Downloading a pre-configured Eclipse Installing pi4soa into an existing Eclipse environment Creating a Choreography Create the Project Create the Choreography Roles and Relationships Resolving Channel Type Errors Creating Participant Types Define the Information Types Defining the Choreography Flow Defining Identity Defining Scenarios Creating Example Messages Creating Example Scenarios With Associated Choreography Simulating Scenarios Defining Scenarios without associated Choreography Participants Message Links Id fields iii

4 iv

5 Chapter 1. Overview 1

6 2

7 Chapter 2. Installation There are two ways to install the pi4soa tool suite. These are discussed in the following sections Downloading a pre-configured Eclipse The recommended approach for installing pi4soa is to use the pre-configured Eclipse installation. This approach installs a full Eclipse environment that has been pre-loaded with the relevant pi4soa plugins and the additional dependencies that are not available in a basic Eclipse installation. The other benefit of the pre-configured Eclipse installation, is that it has a workspace preloaded with the choreography Examples project. This includes artefacts that will be discussed in subsequent sections of this Getting Started Guide. To obtain the latest pre-configured Eclipse installation, go to the download page on the pi4soa sourceforge project page, located at: showfiles.php?group_id= Once the relevant version has been selected, then download the distribution that is appropriate for your operating system. Versions are available for Windows (win32), Mac (macosx) and Linux. Once the distribution has been downloaded, then simply unpack it in your preferred location. The final step is to launch the Eclipse application, which will present a workspace with a single Examples project Installing pi4soa into an existing Eclipse environment If you wish to install the pi4soa plugins into an existing Eclipse environment, then you will need to ensure that certain dependencies are resolved. First step is to ensure the Eclipse version is appropriate. Currently pi4soa supports Ganymede (version 3.4) of Eclipse. This version is available from the Eclipse [ website, in the downloads section. We suggest that you download the Eclipse Classic edition. The next step is to install the other Ganymede related plugins that are required by pi4soa. These are available by selecting the Help->Software Updates... menu item to start the update manager. Once the dialog window is displayed, select the Available Software tab. Then expand the Ganymede top level node, and select the following child nodes, Graphical Editors and Frameworks Models and Model Development 3

8 Chapter 2. Installation If BPMN export is required, then expand the SOA Development and select the BPMN Project Feature child node. as shown in the following screenshot: Once the relevent nodes have been selected, press the Install button to commence the installation of the plugins. Follow the instructions given by the update manager, which will eventually request that the Eclipse application be restarted. Once restarted, your Eclipse environment will have all of the appropriate dependencies, so the next step will be to install the pi4soa plugins. Launch the Software Update Manager again, by selecting the Help->Software Updates... menu item, and then select the Available Software tab. Press the Add Site button, and then enter the URL as shown in the following image. Once the top level node for the new update site has been selected, press the Install button to commence the installation of the pi4soa plugins. Follow the instructions given by the update manager, which will eventually request that the Eclipse application be restarted. Once restarted, your Eclipse environment will be fully configured. Before proceeding with the rest of the chapters in this guide, it will be necessary to install the choreography examples. These can be found at: Select the Choreography examples link and downloading the pi4soa2-examples.zip file. 4

9 Installing pi4soa into an existing Eclipse environment To import the example, select the Import menu item from the popup menu associated with the Eclipse Navigator on the lefthand side of the Eclipse window. When the dialog is displayed, select the Existing Projects from Workspace entry and then press the Next button. 5

10 Chapter 2. Installation Choose the Select archive file radio button and browse to find the downloaded examples zip file. When the file is located, press the Open button and then the Finish button to import the Examples project. Now the Eclipse environment will contain a single Examples project, ready to proceed to the next chapters of this guide. 6

11 Chapter 3. Creating a Choreography In this chapter we will create an example choreography, which can be used in the subsequent chapters. If you do not wish to build the example from scratch, then you can simply read through this section referring to the choreography contained within the Examples project that comes with the pre-configured pi4soa + Eclipse distribution. Alternatively, you can download the project from the examples section on the pi4soa [ website. The choreography that we will be building is located within the file examples/purchasing/ PurchaseGoods.cdm within the Examples project Create the Project 3.2. Create the Choreography Roles and Relationships The first step is to create the choreography file. This can be achieved by selecting the New>Other... menu item from the popup menu associated with a folder in the project. This will result in a further dialog window being displayed, which can be used to select the Choreography Description tree node, and the press the Ok button. 7

12 Chapter 3. Creating a Choreog... When the New Choreography Description wizard is displayed, update the filename from My.cdm to PurchaseGoods.cdm. This will automatically update the Description, Choreography Name and Target Namespace fields. After pressing the Ok button, the choreography editor will be opened on the new choreography description file, showing the Roles and Relationships tab. To create a role, drag the Role item from the palette onto the editor's canvas. This will create a Role entity called Role1 containing a Behavior entity called Role1Behavior. To change the name of the role, select the role entity and go to the Properties view at the bottom of the Eclipse window. This view will show the list of properties associated with the selected entity, which for a role will be its Name and Description. As the name of the role is changed, you will notice that the description is automatically updated. Rename this first role type as Buyer, then drag two more role entities onto the canvas and call them Store and CreditAgency respectively. 8

13 Resolving Channel Type Errors The next step is to define the relationships between the role types. This can be done by selecting the Relationship item from the palette. To establish a relationship select the from role type (i.e. the client role for the relationship) and then select the to role type (i.e. the server role for the relationship). This will create a relationship between the two roles which will be named to reflect the direction of the relationship. Using this technique, create two relationships, one from the Buyer to the Store and the other from the Store to the CreditAgency. The end result should be: Resolving Channel Type Errors At this stage, there should only be two errors associated with the choreography: 9

14 Chapter 3. Creating a Choreog... If you double-click one of the errors, this will navigate to the ChannelType that has reported the validation problem. If you then select the Properties view, you will see the property that has the error: This problem can be resolved by creating a token defining the type of the endpoint reference. By pressing the new, next to the Reference Token property, it will create a default token (e.g. named Token0 in the following image). Then navigate to the Base Types tab, and expand the nodes under the Tokens node. Currently only a single child node will be defined, associated with the newly created channel type's reference token. When the new token has been selected, its properties will be displayed in the Properties view. Firstly set the name property to "URIToken", which will result in the description field also being set. Secondly, press the new button to create an InformationType entity for the token. This will be named after the token: The final step in resolving this issue is to define the XSD element or type associated with the newly created information type. Expand the Information Types node, and selecting the URITokenType and specifying the element or type property, such as: Once the URIToken has been fully configured, then simply double-click on the other error, to set the Reference Token property to URIToken by selecting it from the combo box. 10

15 Creating Participant Types Creating Participant Types The next step is to define Participant Types. These represent the actual parties that will be interacting, and each ParticipantType may implement one or more RoleType. In this specific example, we will have a ParticipantType for each of the previously defined roles. This is the default case, and therefore a participant type would have already been created per role type. This can be confirmed by selecting the Base Types tab, and expanding the Participant Types node Define the Information Types Before we can begin to describe the choreography flow, and the interactions between the participants, we need to specify the information types, representing the type of the messages to be exchanged. Drag the Information Type entry on the palette onto the Information Types node, resulting in a new child element being created called InfoType1. Then select the Properties view and enter the word BuyConfirmed into the Name and Element fields. For simplicity all of the message information types are being created to have the same Name and Element fields, and therefore the elements are being specified without a namespace. Once the BuyConfirmed type has been defined, repeat these steps to create information types for BuyFailed, BuyRequest, CreditCheckInvalid, CreditCheckOk and CreditCheckRequest using the same approach. 11

16 Chapter 3. Creating a Choreog Defining the Choreography Flow Although it would be possible to create other relevant information in the Base Types tab at this stage, we will now move to the Choreography Flows tab to start defining the behaviour associated with the process being modelled. Other type details will be created as a by-product of creating the process flow. Once the Choreography Flows tab has been selected, choose the Interaction entity from the palette and drag it onto the navy blue think line: Once added to the canvas, the interaction will be the focus and therefore the Properties view will display the properties associated with the interaction. Set the Operation to "buy". The next step is to define the channel. If the combo box is selected, you will see that no channels currently exist. Therefore by pressing the new button it will show a popup menu with the available channel types, which have automatically been created based on the role types that were the targets of the relationship links (i.e. Store and CreditAgency). For this interaction, select the StoreChannelType, which will create a channel variable in the current choreography (called StoreChannel), and also set the Relationship property to the value relevant for the channel's target role. Now select the ExchangeDetails element contained within the BuyRequest interaction entity. An interaction can be comprised of multiple exchange details, zero or one request exchange, zero or one normal (non-fault) respond exchange, and zero or more fault respond exchanges. When an interaction is created, a default Request exchange will also be created. When the name of the interaction is defined, this will also update the name of the exchange. In this case, the Action combobox is set to Request, which is appropriate in this situation, but could be set to Respond for normal or fault responses, or Notify. 12

17 Defining the Choreography Flow The final step in defining the interaction is to set the Message Type, which is achieved by selecting the BuyRequest entry from the combo box. This same process should be repeated with a subsequent Credit Check request being sent from the Store to the CreditAgency, with the operation checkcredit on channel type CreditAgencyChannelType. The automatically create Request exchange details should be set to use the CreditCheckRequest message type. At this point in the flow, we need to define a decision point representing the divergence between the paths for a valid and invalid credit check. This is achieved by dragging the Choice construct onto the flow, following the interaction to the credit agency. Then drag two Sequence constructs onto the Choice construct, with the descriptions "Credit Valid" and "Credit Invalid" respectively. In each path of the choice, define two interactions containing Respond exchanges. In one path set the interaction exchanges to CreditCheckOk and BuyConfirmed respectively. In the other path set the interaction exchanges to CreditCheckInvalid (with fault name CreditCheckFailed) and BuyFailed (with fault name BuyFailed) respectively. The fault name can be set on the Advanced tab in the Properties view. The operation name and channel type for the interactions should be the same as for the request that the interaction is responding to, for example, the CreditCheckOk interaction should be on the same channel as the CreditCheckRequest and have the operation name checkcredit. At this stage there should be no errors being reported for the choreography. 13

18 Chapter 3. Creating a Choreog Defining Identity We now have a choreography that outlines the structure of the behaviour with the required ordering of interactions. We have also defined the message types associated with each interaction. However, what is missing is the necessary details concerning how the messages, of those defined types, are correlated to a particular choreography session (or instance). For example, if we see two messages, a BuyRequest followed by a CreditCheckRequest, how can we be sure that these messages relate to the same choreography session, and not two separate choreography sessions (or instances). In WS-CDL, an identity mechanism has been specified that can be used to extract information from the message contents, to enable this correlation to occur. In this example, we will only be dealing with the simplist form of this mechanism, where a single identity token is specified (called ID) to represent a primary key for the choreography, with each message providing access to this id value within their message content. The first step in defining identity within a choreography is to create the identity token. Select the Base Types tab, and drag a Token from the palette onto the Tokens node. This will create a new token with name Token1. Select the Properties view and change the name to be ID. The Type field will currently be empty. Although you could select an existing information type, to define the type for the ID token, for now just press the new button. This will create a new information type called IDType, which can be selected and then a suitable type (e.g. xsd:string) defined. Now that we have defined the identity token, we need to link it to each of the message types that have been exchanged in the choreography. This is achieved by creating a TokenLocator for each message type and token pair, to provide the xpath expression that will locate the token's value within the message content for the specific message type. In some situations, a particular message type may contain information related to multiple tokens, in which case multiple token locators will be defined for the same message type. Although each locator could be created based on knowledge of the token and message types to be handled, one way to ensure that all of the appropriate locators are created is to associate the identity token with the channel types. This association is required to indicate that messages that are exchange over a particular channel type must provide a locator for the tokens associated with that channel type. To associate an identity token with a channel type, expand the Channel Types node in the Base Types tab. Then drag the Identity element from the palette onto the CreditAgencyChanelType. 14

19 Defining Identity Then select the Properties view. You will see a field called Tokens. Press the button at the end of the field to display a selection list with the list of available tokens. Tick the checkbox next to the ID token and press the Ok button. To change the label on the node, set a meaningful description. Once the identity has been defined for the channel type, and the choreography has been saved, you will notice that errors are reported to indicate which interactions have messages being sent on the channel type, but without identity information to enable the messages to be correlated to a particular choreography session. For each of the message type and token pairs reported in the errors, create a token locator by dragging the Token Locator item from the palette onto the Token Locators node. When each locator has been created, set the name to an appropriate value (e.g. CreditCheckInvalidIDLocator, which is based on a combination of the message type and token name) and then set the Token field to ID, Type field to the relevant message type, and finally the Expression field to "//@id". This xpath expression will be common to all locators within this example choreography, and is specified for simplicity. In reality, each message type may have more specific xpath expressions to locate the information of interest. Once the token locators have been created for the credit check interactions, then associate the ID token with the StoreChannelType channel type. Instead of dragging a new Identity element from the palette, select the ID identity entity contained within the CreditAgencyChannelType and copy it (either using the Copy menu item on the Edit menu, or using the Ctrl-C shortcut). Then select the StoreChannelType and press the Ctrl-P shortcut (or Paste menu item from the Edit menu). This will create an ID identity element for the StoreChannelType. Once the choreography has been saved, then create the token locators to fix the new set of errors that have been created. 15

20 16

21 Chapter 4. Defining Scenarios In this chapter we will create a scenario. A scenario can be considered an enhanced sequence diagram, as it represents the interactions between a set of communicating parties, that reflects a particular path (or use case) through a business process. The scenario differs from a standard sequence diagram in that it includes an example message with each interaction, that can be used for simulating the scenario against either the choreography or an actual implementation of the parties (i.e. services) defined in the choreography. Although in this Getting Started Guide we are creating the scenario after the choreography has been defined, it is possible to create the scenario before the choreography exists. The benefit of this approach is that the scenarios can be used to document the business requirements for the distributed system being built. The disadvantage is, that as the choreography does not exist, it cannot be used to provide context information to the scenario editor, to help build the scenario. In the following sections, we will first describe the creation of scenarios where a choreography already exists, and therefore provides context information to help define the scenario. However in a later section we will also explore how a scenario can be created where no choreography exists. If you do not wish to build the scenario from scratch, then you can simply read through this section referring to the scenario contained within the Examples project that comes with the preconfigured pi4soa + Eclipse distribution. Alternatively, you can download the project from the examples section on the pi4soa [ website. The scenario that we will be building is located within the file examples/purchasing/ SuccessfulPurchase.scn within the Examples project. This scenario represents a valid purchasing use case, where a Buyer sends a buy request to a Store, which then performs a credit check request to a CreditAgency. In this scenario the CreditAgency returns a 'credit ok' response, and therefore the Store returns a confirmed response to the Buyer Creating Example Messages As mentioned above, the difference between a pi4soa scenario, and a standard sequence diagram, is principally that it associates an example message with each interaction. These messages can either be included within the model, as a property on the message links, or defined externally within an XML file that is referenced by the message link as a URL. In this chapter, we will be defining the messages in their own XML files, which has the benefit of enabling the message to be re-used by multiple message links across multiple scenarios. In the scenario described above, there are four messages required, one for each of the four interactions. In this simple example, the files can be named after the message type. 1. BuyRequest.xml 17

22 Chapter 4. Defining Scenarios <BuyRequest id="1" /> 2. CreditCheckRequest.xml <CreditCheckRequest id="1" /> 3. CreditCheckOk.xml <CreditCheckOk id="1" /> 4. BuyConfirmed.xml <BuyConfirmed id="1" /> As you can see, these example messages are not particularly elaborate. However they provide the core information required when simulating a scenario against a choreography, the message type (in this case provided by the top level element), and the identity fields (which in this case is simply the id attribute on the top level element). These example messages can be as elaborate as is required to express the requirements of the system, as long as they contain the core information required to identity the message type and identity for the purposes of correlating the message against an interaction in an associated choreography Creating Example Scenarios With Associated Choreography The first step is to create the scenario file, for the specific use case outlined above. This is achieved by selecting the New->Other... menu item, associated with the examples/purchasing folder. 18

23 Creating Example Scenarios With Associated Choreography When the following dialog window has been displayed, select the Scenario entry in the Choreography category. Then press the Next button. Enter the file name for the scenario, in this case SuccessfulPurchase.scn and press the Finish button. This will cause the empty scenario to be displayed in the Scenario Editor. 19

24 Chapter 4. Defining Scenarios The next step is to configure the top level properties associated with the scenario, as presented in the Properties view. In this situation, the choreography description has previously been defined and therefore the relative path to the PurchaseGoods.cdm file can be specified. The other important property is the name, but the description field is optional. The next step is to place the participants onto the canvas. This can be achieved by dragging the Participant item from the palette onto the background. This should be done three times, one time per participant that we want to represent in the scenario. To configure each participant, select it from the diagram and then define its type by selecting the appropriate value from the Type field in the Properties view, as shown below. This should be done for the BuyerParticipant, StoreParticipant and CreditAgencyParticipant. Note In the preconfigured PurchaseGoods.cdm choreography and scenarios, the participant type names have been updated to remove the Participant suffix. However, if building the choreography, as described in the previous section, then this suffix will still be included, and therefore present in the entries in the dropdown menu for the Type field. Now we are in a position to define the interactions between the participants to specify the use case. This can be achieved by selecting the Message Link item from the palette, then selecting the from participant, and dragging the link to the to participant. This will cause a message link to be defined between the two points, with the label Unknown to reflect the fact that no message definition has currently been assigned to the link. 20

25 Creating Example Scenarios With Associated Choreography While the newly created message link is selected, select the dropdown menu associated with the Message field in the Properties view. This menu will contain any messages that are valid between the two relevant participants, in the direction indicated by the message link. For the first message link, between the BuyerParticipant and StoreParticipant, will list the buy(buyrequest) message definition only. This entry should be selected. The only other field that needs to be filled in, at this stage, is the reference to the relevant example message. For this message link the Value URL field should be set to BuyRequest.xml. To complete this first scenario, create the following three remaining message links: 1. Credit Check Request Create the message link by dragging the line from StoreParticipant to CreditAgencyParticipant. Then select the checkcredit(creditcheckrequest) item from the Message dropdown menu, and specify the Value URL field as CreditCheckRequest.xml. 2. Credit Check Ok Create the message link by dragging the line from CreditAgencyParticipant to StoreParticipant. Then select the checkcredit(creditcheckok) item from the Message dropdown menu, and specify the Value URL field as CreditCheckOk.xml. 3. Buy Confirmed Create the message link by dragging the line from StoreParticipant to BuyParticipant. Then select the buy(buyconfirmed) item from the Message dropdown menu, and specify the Value URL field as BuyConfirmed.xml. This should result in the completed scenario looking like this: 21

26 Chapter 4. Defining Scenarios 4.3. Simulating Scenarios Once a choreography description has been associated with a scenario, by setting the Choreography Description URL field associated with scenario's properties, and the scenario has no errors reported in the Problems view, then it will be possible to simulate the scenario against the choreography description. To simulate the scenario, either press the green 'play' button in the toolbar, or use the popup menu associated with the Scenario Editor, to select the Scenario->Simulate menu item. When a scenario is being simulated against a choreography, initially each node will turn yellow indicating that processing of that event has begun. It will then either turn green if it was successfully simulated, or red if an error occurred. In the case of this specific scenario, created against the choreography defined in the previous chapter, the end result should be as shown below. 22

27 Simulating Scenarios To demonstrate the effect when there is a mismatch between what has been defined in a scenario and the associated choreography, first we must reset the simulation. This can be achieved by selecting the red 'reset' button on the toolbar, or use the popup menu associated with the Scenario Editor, to select the Scenario->Reset Simulation menu item. One the simulation has been reset, then select the final buy(buyconfirmed) message link, and change the Message field in the Properties view to select the buy(buyfailed) fault sens:buyfailed entry. Once the scenario has been re-saved, then run the simulation again, and you should see the following result: 23

28 Chapter 4. Defining Scenarios The node that is highlighted in 'red' identifies that sending this message type, from the StoreParticipant is invalid based on the behaviour specified in the choreography description. However, from the perspective of the BuyerParticipant it is valid to receive a buy(buyfailed) message in response to a buy(buyrequest), and therefore the node at the other end of this message link is shown in 'green' Defining Scenarios without associated Choreography This section outlines the differences that will be observed when building a scenario without an associated choreography description. For example, where a new system is being designed, the scenarios can be used to document the requirements before a choreography description is specified Participants The first difference to be aware of is when configuring the participants within the scenario. As outlined previously, the Participant palette entry is used to create participant entries in the scenario, and can be configured using the fields in the Properties view. When a choreography description is associated with the scenario, it is possible to select the Participant Type defined within the choreography description from a dropdown menu associated with the Type field. When a choreography description is not associated with the scenario, the Type field cannot be specified. This field can only be specified once a choreography description has been created, and associated with the scenario. Therefore, at this stage in the specification of the scenario, it will only be possible to define information in the instance field. This can be used to provide a hint to the choreography designer, of the nature of the participant, which may help the choreography designer to group relevant 'participants' into Role Types and Participant Types within the choreography Message Links The configuration of the details associated with a Message Link differ depending on whether a choreography description is associated with a scenario. As previously described, an associated choreography description provides context that can be used to present a dropdown list of message definitions to be associated with the link. Where this context information is unavailable (i.e. when no choreography description URL is defined for the scenario), it is necessary for the user to specify individual pieces of information that collectively identify the interaction details, as shown in the following image. 24

29 Id fields These fields of interest are: Operation Name This field is optional at this stage. If the message type is unique enough to distinguish the message, in the context of the sending and receiving participants, then the operation name does not have to be specified at this point. Fault Name This field is optional in general, and is only used to indicate that a response to a previous request (with the same operation name) is a fault of a particular type. However, if the operation name is not defined at this stage, then equally the fault name does not need to be, as long as the message type is distinct for the fault in question. Is Request This field is used to specify whether the message exchange represents a request (and therefore will be true), or a response/fault/notification (and therefore will be false). Message Type This field is mandatory, and defines the type of the message being exchanged. The format of the field is "{namespace}localpart". The namespace is optional, and can therefore be excluded as in the image above. Note When the choreography description is built, and the URL is set in the scenario, each message link/event should have an appropriate Message property which links to the message definition (combination of operation name, message type, direction, etc) in the choreography. If the appropriate message definition for the details specified in the scenario's message link cannot be found in the associated choreography description, then the Message property will show as blank Id fields The final aspect of the scenario we wish to look at is also associated with the Message Link or nodes at either end of the link. These are the Session Id and Channel Id fields. 25

30 Chapter 4. Defining Scenarios These fields are listed in the Properties view for the selected component, either if no choreography description has been associated with the scenario, or if associated choreography description does not declare any explicit identity information. If the intention is to define explicit identity information within a choreography description, to be associated with the scenario, then no information needs to be placed within these fields. However, if the scenario is to be associated with a choreography description that will not define explicit identify details, then values should be supplied for these fields. The Session Id should have a consistent value throughout the scenario. However the Channel Id should use a distinct id value for each set of interactions between two participants. For example, for each interaction between participant A and B, the channel id could be 'X', but for each interaction between B and C, the channel id could be 'Y'. 26