Petals Master User Guide This document describes the installation and usage of Petals Master, the web application for SOA Gorvernance, by eBM WebSourcing.
Petals Master Team Anne-Marie BARTHE Olivier FABRE - December 2008 -
(CC) EBM WebSourcing - This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/3.0/
Petals Master User Guide
Table of Contents Structure of the document ........................................................................................................................ 3 1. Pre-requisites ...................................................................................................................................... 4 2. Presentation of Petals Master ................................................................................................................. 5 3. Installation ......................................................................................................................................... 6 3.1. Configure a database and a Lucene index ...................................................................................... 6 3.2. Installing the application ............................................................................................................ 8 3.3. Accessing the application ........................................................................................................... 8 4. Petals Master Administration ............................................................................................................... 10 4.1. Initialize Petals Master Database ................................................................................................ 10 4.2. What does the button "Rebuild Search Index" do? ......................................................................... 10 5. Petals Master organizations management ................................................................................................ 11 5.1. Create an organization .............................................................................................................. 11 5.2. View/edit an organization ......................................................................................................... 11 5.3. Add posts to an organization ..................................................................................................... 14 5.4. Create a post .......................................................................................................................... 14 5.5. View/edit a post ...................................................................................................................... 15 5.6. Delete a post .......................................................................................................................... 15 5.7. Create a person ....................................................................................................................... 15 5.8. View/edit a person .................................................................................................................. 16 5.9. Delete a person ....................................................................................................................... 16 5.10. How does the search engine work ? .......................................................................................... 16 5.11. Search organizations .............................................................................................................. 17 5.12. Search persons ...................................................................................................................... 17 5.13. Search posts ......................................................................................................................... 18 6. Petals Master services management ....................................................................................................... 20 6.1. How to import a service ........................................................................................................... 20 6.2. View service's information (purpose, endpoints, actors, etc.) ............................................................ 21 6.3. View service's endpoints ........................................................................................................... 23 6.4. Search services ....................................................................................................................... 26 7. Petals Master Runtime Management ...................................................................................................... 27 7.1. Add a Runtime Manager .......................................................................................................... 27 7.2. Edit a Runtime Manager and Synchronize Execution Environment with Petals Master Registry .............. 27 7.3. Edit an Execution Environment ................................................................................................. 28 7.4. Edit a Processor ...................................................................................................................... 29 7.5. Edit an Environement Federation ............................................................................................... 29 7.6. Search Runtime Manager, Processor, Execution Environments and Environment Federations ................. 30 8. Petals Master Web Services APIs ......................................................................................................... 31 8.1. The UDDI WS API ................................................................................................................. 31 8.2. The Petals Master specific API .................................................................................................. 31 9. Adding custom Category/Identifier systems for Organizations/Services/Endpoints .......................................... 33 9.1. Adding custom categorisation system and associated values ............................................................ 33 9.2. Adding custom identification system ........................................................................................... 34
Petals Master User Guide
2
Structure of the document
Structure of the document This document describes the installation and the use of Petals Master. It is designed for Petals Master users.
Petals Master User Guide
3
Pre-requisites
Chapter 1. Pre-requisites Before installing the Petals Master web application, be sure that you have installed the following elements : • A JDK 1.5.0 or later, • A servlet container like Apache Tomcat 5.5.26 or later, • A Web navigator like : • Firefox 2.0 or later with Javascript activated, • Chrome with Javascript activated, • Internet Explorer 6 or later with Javascript activated, • Opera 9.6 or later with Javascript activated, • Safari 3.1.2 or later with Javascript activated. • Optional : A relationnal database like : • MySQL 5.0 or later, • H2 1.1 or later, • HSQL 1.8.0 or later (HSQL DB is fully supported only in server mode). By default, Petals Master is configured to use H2 database, which is embedded into Petals Master (the H2 is configured in memory mode).
Petals Master User Guide
4
Presentation of Petals Master
Chapter 2. Presentation of Petals Master Petals Master is made of four parts : • Administration : allows you to manage Petals Master database, settings, etc. • Organizations management : allows you to manage the entities like organizations, posts and persons. • Services management : in this section you can add services to the registry, search services into the registry, etc. • Runtime Management : allows you to connect Petals Master to a Service execution environment like an Enterprise Service Bus (PEtALS), an Application Server, etc. Please note that the application is available in English and soon in French ! In the future, to change the used language, click on the choosen country flag (located on the top right side of the application).
Petals Master User Guide
5
Installation
Chapter 3. Installation 3.1. Configure a database and a Lucene index The default configuration of the Petals Master application uses an H2 database, in non-persistent mode (memory mode). That means that when the servlet container is stopped, all the data are deleted (because they were not persisted). You may want to change this configuration : use H2 database but in file mode (to persist data), or change the H2 database for a MySQL database for example. We will see how to do that. Petals Master uses a Lucene index to store information about stored entities to provide advanced search capabilities. The default configuration stores the index in memory. So, if the servlet container is stopped, the index is lost. This default setting must only be used with a non persistant storage (H2 in memory mode). This configuration must be modified if you use a persistant storage like H2 in file mode or MySQL. We will see below, how to configure a file system directory for index purpose. Petals Master is packaged as a war. To change the database configuration, you have to unzip the war archive. Go into the ${petals-master-root}/WEB-INF/classes directory and open the dragon.properties file. The default dragon.properties file is (NB : here, we have disable the MySQL configuration and enable the H2 configuration, Indexation is set in memory mode) :
The H2 Datasource (in memory mode) is the one used by default. You also have a MySQL configuration which is disabled by default. Let's have a look at the available parameters (these parameters values are to adapt according to the used database) : • jdbc.driverClassName : this is the JDBC driver which enables the connection between the Java application and the database. A list of available JDBC drivers is available at JDBC Data Access API.
Petals Master User Guide
6
Installation
• jdbc.url : this is the URL of the database. • jdbc.username : this is the username of the account used to access to the database. • jdbc.password : this is the password of the account used to access to the database. • jdbc.dialect : this is the Hibernate dialect allowing the translation of SQL information to the targeted database. Available Hibernate dialects are : • H2 : org.hibernate.dialect.H2Dialect • MySQL : org.hibernate.dialect.MySQLDialect • MySQL 5 with InnoDB : org.hibernate.dialect.MySQL5InnoDBDialect • MySQL with InnoDB : org.hibernate.dialect.MySQLInnoDBDialect • MySQL with MyISAM : org.hibernate.dialect.MySQLMyISAMDialect • HSQLDB : org.hibernate.dialect.HSQLDialect • jdbc.hbm2ddl.auto : this parameter defines if the application creates a new database from scratch (create) or only update an existing database (update). Update mode also create a database if it doesn't exist. Except for an H2 in memory mode, it is recommended to set the value at update. Let's have a look at the available parameter for the indexation : • compass.index.url : the index URL, "ram://path" for an in memory index, "file://path" for a file system persisted index. • compass.engine.analyser.default.type : type of analyser used to tokenize indexed information. Petals master comes with core analyzers (Which are part of the lucene-core jar). They are: standard, simple, whitespace, snowball, and stop. • standard : tokenize information with the following rules. Splits words at punctuation characters, removing punctuation. However, a dot that's not followed by whitespace is considered part of a token, splits words at hyphens, unless there's a number in the token, in which case the whole token is interpreted as a product number and is not split, recognizes email addresses and internet hostnames as one token.Then lowercase tokens and remove english stop words (the, a, an ...). It is the recommended and most tested analyser. • simple : tokenize information by dividing text at non-letters. That's to say, it defines tokens as maximal strings of adjacent letters, as defined by java.lang.Character.isLetter() predicate. Note: this does a decent job for most European languages, but does a terrible job for some Asian languages, where words are not separated by spaces.Then lowercase tokens. • whitespaces : tokenize information by dividing text at whitespace. • snowball : same as standard analyser but stems words using a Snowball-generated stemmer. • stop : same as simple analyser but remove english stop words (the, a, an ...). • compass.engine.analyser.default.name : An additional setting that must be set when using the snowball analyzer. The settings can have the following values: Danish, Dutch, English, Finnish, French, German, German2, Italian, Kp, Lovins, Norwegian, Porter, Portuguese, Russian, Spanish, and Swedish. Other parameters (not visible in the previous screenshot) : • configuration.reload.delay : this property specify the delay between 2 consecutives reload of the Petals Master configuration. Must not be modified. • root.domain : used to generate UDDI keys. By default the root domain is "dragon.org". You could specify your own root domain. For exemple : "mycompany.com". See Chapter 9, Adding custom Category/Identifier systems for Organizations/Services/Endpoints Petals Master User Guide
7
Installation
3.2. Installing the application Petals Master is packaged as a WAR archive, you just have to deploy it in your servlet container. If you have previously unwar the Petals Master archive to set your own database configuration, you have two ways : • Copy/paste your Petals Master directory directly into your serlet container, • Zip your Petals Master directory as a WAR archive, then copy/paste this new archive into your servlet container (into the WebApp directory if you use Tomcat). For instance, Tomcat users just have to copy the war to the webapps directory and wait for Tomcat to deploy the application.
3.3. Accessing the application Once deployed, Petals Master can be accessed in your web browser through the address http://host:port/petals-master${version-number}/petals-master. If your server configuration has "localhost" as host, 8080 as port, the URL for Petals Master V1.0 is : http://localhost:8080/petals-master-1.0/petals-master.
You reach the Login page of the application. You can choose to remember your logging information for two weeks. Petals Master is setup with two default users : • An administrator allowed to access to all Petals Master features : Username "master" / Password "master" • A simple user having limited access rights : Username "user" / Password "user" You can add/remove users by editing the applicationContext-security.xml file that sits in the same directory as the dragon.properties file (${petals-master-root}/WEB-INF/). You must edit this part of the file : - - - - - - - - - - - -
Petals Master User Guide
8
Installation
- -
Two roles are available : ROLE_ADMIN and ROLE_USER. All users must have at least the ROLE_USER role. Passwords must be encoded in md5. An online encoder is available at http://7thspace.com/webmaster_tools/ online_md5_encoder.html. Once you are sucessfully logged in, you can see the following screen :
Please note that in the following screenshots, when you see a field with a yellow foreground, it means that the field is required.
Petals Master User Guide
9
Petals Master Administration
Chapter 4. Petals Master Administration 4.1. Initialize Petals Master Database You could initialize the Petals Master database by providing an XML dataset that conforms to the dragon-dataset.xsd XML schema included in the ${petals-master-root}/WEB-INF/classes/dataset/. Some dataset samples are available in this directory. To load a dataset two tabs are available : The first tab "Dataset URL Import" :
Fill the field with dataset file URL. You can load a dataset sample available in the "${petals-master-root}/WEB-INF/ classes/dataset/" directory by entering an URL like this : classpath:dataset/dataset-file-name The second tab "Dataset File Import"
Browse your files and choose your dataset.
4.2. What does the button "Rebuild Search Index" do? If you notice any inconsistencies in search organizations, persons or services, this may be a timing issue between the database and the search index. Click "Rebuild Search Index" which will synchronize the search index with your database.
Petals Master User Guide
10
Petals Master organizations management
Chapter 5. Petals Master organizations management 5.1. Create an organization What is an organization ? This can be a company, a part of a company, a unit of a company. An organization provides services, human resources (called person here), has positions (called post here). To create an organization, you have to fill : • The name of the organization, • The contact e-mail of the organization, • The name of the city where the organization is located, • The name of the country where the organization is located. Optional elements to fill are : • The legal status of the organization, • The type of organization (Small Business, etc.), • The Website of the organization, • The Mother organization name of the organization (the current new organization can be a part/ an unit of an other organization, • Concerning the organization's address : the street number, the street name, the zipcode, the state.
5.2. View/edit an organization The next screen after creating an organization is the "View/Edit" screen. The screen is set on view mode (default). To edit the data, you have to click on the Edit button. You can see four tabs :
• The Identity Card tab : there you can view the previous data that you have given to register the current organization.
Petals Master User Guide
11
Petals Master organizations management
• The Other Info tab : here you can view categories and identifiers
You can define categories, for example countries where organizations are located. Simply click "add" to define a new category. Some categorization systems comes with default values and descriptions. Others let you define your own values and descriptions. To delete categories, just tick them in the list and click Delete button.
UDDI defines a set of identifier systems (DUNS, Thomas Register...) that are international identification systems for organizations. Simply click "add" to define a new identifier for the current organization. You must specify a value and a human readable description for each added identifier. To delete identifiers, just tick them in the list and click Delete button.
Petals Master User Guide
12
Petals Master organizations management
• The Organization's posts tab : there you can view the various positions of the organization (e.g.: manager, developer, etc.). You can also add a position to the list. For this purpose, you can create a new Post (i.e. create a new position, available for all the companies registered on Petals Master into the posts' list), or you can add an existing position, choosen via the posts' list.
We will see later how to create (see Section 5.4, “Create a post”) and add (see Section 5.3, “Add posts to an organization”) posts to an organization. Note that if you click on the name of the post in the list, you can see the complete "id card" of this post and edit its information.
• The Organization's persons tab : there you can view the several persons who have a role on the SOA governance into the current organization. You cannot create a person if there is no post linked (via "create" or "add" actions seen below) to the organization. You need to create a person, who will automatically appear into the list. A person has a firstname, a middlename, a lastname, a post, an e-mail address, a phone number and a localization (where does he/she work ?).
We will see later how to create a person (see Section 5.7, “Create a person”). Note that if you click on the name of a person in the list, the complete data about him/her appears, and you can edit it.
Petals Master User Guide
13
Petals Master organizations management
5.3. Add posts to an organization Previously, we have seen that an organization owns several posts. A post can be also linked to many companies (ex : "HR Manager" is a position owned by many companies). So, you can add to Company B a post previously created for Company A (this post was automatically added to Company A). You don't need to duplicate this post to add it to Company B. Come back on the View/Edit form of the organization. We have the following screen :
Click on the Add Post Button. Now you see a list of posts :
A multiple selection is allowed (by pressing CTRL while clicking on the name of the posts you want to add to the current organization). After validating your choice, you automatically go back to the list of posts. Please note that the posts list to add is updated after each adding of post. As a consequence, an added post won't appear in the list so you cannot add twice the same post (avoiding double data). When the list is empty, the Add button is disabled (it's time to think about creating new posts !).
5.4. Create a post If there is no post matching the position you want to add to the organization, you have to create it. Go back on the Organization's post tab. Click on the Create Post button : you are now on a form to create a post. This post will be automatically added to the current organization and will be also available into the list of available posts to add of the other organizations. To create a post, you have to fill : • The name of the post (ex: Developer), • The nature/type of the post (ex: IT), • The description of the post (a brief description that underlines the skills of the post).
Petals Master User Guide
14
Petals Master organizations management
5.5. View/edit a post When you click on a post into the list of posts, you can see its whole information and edit (click on the Edit button to change data).
5.6. Delete a post To delete a post from the list of posts of an organization, you have only to click on the Delete link at the right side of the array. A message box asks you to confirm the deletion of the post s(the post is not deleted from the database, only the link between the post and the current organization is broken). The deleted post is now available into the choice list of the Add post form... so you can add it again !
Caution If a post is used by a person in the current company, the Delete link is disabled. Only a non-used post can be deleted !
5.7. Create a person The next step you should do is to create persons. What is a person ? This is not a user. This is someone who has interactions with services, as a manager, a designer, a developer, a hot liner, etc. A person is linked to an organization and has a post. To create a person, go into the "Organisation's persons" tab of an organization.
Click on the button "Create person", fill in the following form.
Petals Master User Guide
15
Petals Master organizations management
The mandatory fields are : • The title of the person, • The first name of the person, • The last name of the person, • The Email address of the person, • The post of the person. Optional fields to fill are : • The middle name of the person, • The phone number of the person, • The localization of the person (ex. : Building 5, office B45),
5.8. View/edit a person When you click on the name of a person (into the list of persons of the current organization), you see the View/Edit form.
You can edit the data : click on the Edit button, then you are allowed to modify fields values. Then click Save to register updated data.
5.9. Delete a person To delete a person from the list of persons of an organization, you have only to click on the Delete link at the right side of the array. A message box asks for confirmation of the deletion of the person (the person is definitively deleted from the database, you cannot undo this action).
5.10. How does the search engine work ? Before presenting the search forms, have a look on the Petals Master search engine. The search engine is based on the logical expression AND. e.g., you are searching a company located in Villepreux, whose name is Lacoera. And, you are making a search on two fields : the organization's name and the organization's city. The search engine will return all the results that contain Lacoera into the name field and/or the city field AND that contain Villepreux into the name field and/or the city field. You can use wildcards in the keywords : • To perform a single character wildcard search use the "?" symbol. To search for "text" or "test" you can use the search: te?t
Petals Master User Guide
16
Petals Master organizations management
• To perform a multiple character wildcard search use the "*" symbol. To search for test, tests or tester, you can use the search: tes* • To perform a fuzzy search use the tilde, "~", symbol at the end of a Single word Term. For example to search for a term similar in spelling to "roam" use the fuzzy search roam~. This search will find terms like foam and roams. • To escape special characters like + - && || ! ( ) { } [ ] ^ " ~ * ? : \ use the \ before the character. For example to search for (test):toto use the query: \(test\)\:toto
Note Don't escape special caracters in your key words if they are URIs like service fullnames ({http:// www.foo.net}FooBar).
5.11. Search organizations In the left vertical menu, you have a link to the Search Organizations form.
You can restrict search results by ticking search criteria (restrict the number of fields where the key words will be searched). To display the list of all Organizations in Petals Master database push the "See All" button. E.g., if you tick "Organization name" and "Type of organization", with the context of the "Lacoera Villepreux" search seen previously, there will be no search results, because there is no organization which name equals "Lacoera" or "Villepreux" and type of organization equals "Lacoera" or "Villepreux" ("Villepreux" is only present in a city name !). To find Lacoera organization with these key words you have to tick "Organization name" and "Localization".
To access the organization data, click on its name : the view/edit form appears.
5.12. Search persons In the left vertical menu, you have a link to the Search Persons form.
Petals Master User Guide
17
Petals Master organizations management
You can restrict search results by ticking search criteria (restrict the number of fields where the key words will be searched). To display the list of all Persons in Petals Master database push the "See All" button. For example, we search all the Java developers from the organization named Lacoera. So we tick Organization and Post.
To access the person data, click on its name : the view/edit form appears.
5.13. Search posts In the left vertical menu, you have a link to the Search Posts form.
You can restrict search results by ticking search criteria (restrict the number of fields where the key words will be searched). To display the list of all Posts in Petals Master database push the "See All" button. For example, we search all the technical posts. So we tick Nature.
Petals Master User Guide
18
Petals Master organizations management
To access the post data, click on its name : the view/edit form appears. To totaly remove a post from the Petals Master database, just click on the delete link. Deletion is allowed only if the post isn't linked to persons or organizations.
Caution be careful, it is different from the previously described remove method that only unlink post from an organization
Petals Master User Guide
19
Petals Master services management
Chapter 6. Petals Master services management In this part of the documentation, we will see how to import services into Petals Master's registry, how to search services, add organization's and person's roles on services and endpoints .
6.1. How to import a service Importing a service into Petals Master's registry is really simple. Go to the "Import service" page. You will see this : You have two tabs. The first tab "WSDL URL Import" :
You have only to copy/paste the URL of the service's WSDL into the field, then validate.
The second tab "WSDL File Import" :
Here, browse your files and choose the service's WSDL. You will be forwarded to a new screen, displaying the service(s) described by the uploaded WSDL and then registered into Petals Master.
To display service's information (like the roles of the actors (provider, consumer, developer, user, etc.), categorization, brief description of the aim of the service, etc.), click on the service's name : you will arrive on the View/Edit form of the service.
Caution UI import functionalities allows import of WSDL with absolute imports or without imports. Only Petals Master Web Service API allows to import WSDL with relative imports. See Chapter 8, Petals Master Web Services APIs
Petals Master User Guide
20
Petals Master services management
6.2. View service's information (purpose, endpoints, actors, etc.) You have several tabs on this form. The first is the service's ID card. There, you can fill pieces of information about its purpose and other stuff (select the Edit button to edit/add data). You can rate the service by clicking the stars labeled as "My rating". The stars labeled as "Global rating" provide the average users rating.You could also tag services by clicking "New Tag" and providing a comma separated list of tags. If you want see the service's WSDL (the one you provide to register the current service) click on the link of the download column.
The second tab is named Other Info . If you click on it, you can see several categories defined for this service. You could add new categories by clicking Add button. To delete categories, just tick them in the list and click Delete button.
The third tab is named Endpoints. This tab displays all of the service's endpoints (as defined by the service's WSDL).
Like for services, view information about endpoints is possible. You just have to click on the endpoint's name and its information will be displayed. We will detail it later (see Section 6.3, “View service's endpoints”). The fourth tab is named Organization's roles. This tab displays the roles of the organizations. If the service is newly registered, there is no organization's role at all.
To add an organization's role, it is very simple. Click on the 'Create organization's role' button, then fill in the form : choose an organization, then choose a role and validate.
Petals Master User Guide
21
Petals Master services management
Then, the organization's role appears into the array :
You can filter the array data by role. E.g. select the user role into the list :
and you obtain :
The fifth tab is named Person's roles. This tab displays the roles that persons of an organization have on the current service. If the service is newly registered, there is no person's role at all.
To add a person's role, it is very simple. Click on the 'Create person's role' button, then fill in the form : choose an organization, choose a person, then choose a role and validate.
Then, the person's role appears into the array :
You can filter the array data by role. E.g. select the user role into the list :
and you obtain :
Petals Master User Guide
22
Petals Master services management
The sixth tab is named Related Docs. Here, you can attach documents relating to the service (authorized formats: .DOC, .PDF, .XML, .HTML, .XLS, .PPT, .TXT, .RTF, .ODT, .ODS, .ODP).
browse your files and choose your document.
The seventh and last tab is named Comments. Here you can write comments for the service and see other user comments.
6.3. View service's endpoints To view and edit information about an endpoint (like the roles of the actors (provider, consumer, developer, user, etc.)), click on the endpoint name (reachable via the 'Endpoints' tab of the Service View/Edit screen, as seen previously). You will arrive on the endpoint's ID card. There, you can fill pieces of information about its purpose and other stuff. You can rate the endpoint (click the stars) and define tags (click New Tag). If you want to see the service's WSDL (which owns the current endpoint) click on download.
Petals Master User Guide
23
Petals Master services management
The second tab is named 'Other Info'. Here you can add categories for this endpoint :
To add categories, click the button "add"
You obtain :
The third tab is called 'Operations'. This tab displays all the endpoint's available operations, as you can see below.
Petals Master User Guide
24
Petals Master services management
The fourth tab is named 'Organization's roles'. This tab displays the roles of the organizations. If the service (and so, the endpoint) is newly registered, there is no organization's role at all.
To add an organization's role, it is very simple. Click on the 'Create organization's role' button, then fill in the form : choose an organization, then choose a role and validate.
Then, the organization's role appears into the array :
The fifth is named 'Person's roles'. This tab displays the roles that persons of an organization have on the current endpoint. If the service (and so, the endpoint) is newly registered, there is no person's role at all.
To add a person's role, it is very simple. Click on the 'Create person's role' button, then fill in the form : choose an organization, choose a person, then choose a role and validate.
Petals Master User Guide
25
Petals Master services management
Then, the person's role appears into the array :
A role (organization role or person role) added to an endpoint is automaticaly added to the parent service. The sixth and last tab is named Comments. Here you can write comments for the endpoint and see other users commnets.
6.4. Search services The use of the services search engine is similar to the one for organizations and persons. Enter your keywords and select fields on which the engine will search.
To display the list of all Services in Petals Master database push the "See All" button. The results are displayed as following :
Petals Master User Guide
26
Petals Master Runtime Management
Chapter 7. Petals Master Runtime Management This chapter describe how to connect Petals Master to a Service Execution Platform like an Enterprise Service Bus (PEtALS, etc.), an Application Server (Jonas, JBoss, etc.). In this chapter you will heard about Runtime Manager, Processor, Execution Environment, Environment Federation. Here are the description of each concepts : • Runtime manager : this entity is an agent that have a high level vision of a Service Execution Platform or a group of Service Execution Platform (Federation, Grid, etc.). It is the communication intermediate between Petals Master and the Service Execution Platform(s). It implements a connection interface provided by the Petals Master project. • Processor : this entity is a server that host Service Execution Platform. For exemple it could be an IBM Server. • Execution Environment : this entity is a Service Execution Platform like an ESB node (PEtALS single node, etc.), an Application Server (Jonas server, etc.). For the moment, Petals Master connection API is only implemented by Petals ESB. • Environment Federation : this entity is a group of Execution Environment (Service Execution Platform) that follow a given federation pattern like FEDERATION, GRID, DISTRIBUTED, etc. PEtALS domains, which are group of PEtALS ESB nodes, are examples of Environment Federation.
7.1. Add a Runtime Manager To add a runtime manager to Petals Master registry, you just have to provide the address of the manager connection service :
The manager connection service must be a Web Service that implements the WSDL connection interface provided by the Petals Master project. An implementation of this interface is already available for the PEtALS Service Platform. Once you have successfuly added a new Runtime Manager, you are redirected to the edition page of the newly imported Runtime Manager.
7.2. Edit a Runtime Manager and Synchronize Execution Environment with Petals Master Registry The first tab, "Identity Card", provides information about the Runtime manager itself like its name and address. Here you could remove a runtime manager by clicking the delete button.
The second tab, "Execution Environments", show the list of Execution Environments managed by this Runtime Manager. The first time you show this tab, no execution environments are available.
Petals Master User Guide
27
Petals Master Runtime Management
You must synchronize your manager with the Petals Master registry to see managed execution environments. Simply push the "Synchronize Execution Environments" button.
All managed execution environments are synchronized, but also linked endpoints with their descriptions (so related Services, Interface, etc.), host processors (Servers, Mainframes, etc.) and environment federations. You can click on the execution environment name to see all information about it.
7.3. Edit an Execution Environment The first tab of the Execution Environment editor provides identity information like its name, type (ESB, Application Server, etc.), address (host address), host processor (the server that host the exec env) and parent federation if the exec env is member of a group of exec envs (in case of federation, distribution, grid, etc.). Here you could remove an execution environment by clicking the delete button.
If you click on the host processor "view details" link, you are redirected to the Processor editor page. If you click on the parent federation "view details" link, you are redirected to the Environment Federation editor page. The second tab of the Execution Environment editor provides the list of all endpoints hosted on this execution environment.
Petals Master User Guide
28
Petals Master Runtime Management
7.4. Edit a Processor The first tab of the Processor editor provides identity information like its name and address (IP v4 address). Here you could remove a processor by clicking the delete button.
The second tab of the Processor editor provides the list of all Execution Environments hosted on this processor.
The third tab of the Processor editor provides the list of all endpoints hosted on the processor. This list contains all endpoints hosted on all execution environments hosted on this processor.
7.5. Edit an Environement Federation The first tab of the Processor editor provides identity information like its name and federation pattern (Distributed, Federated, Grid, etc.). Here you could remove a federation by clicking the delete button.
The second tab of the Processor editor provides the list of all Execution Environments that are members of this federation.
Petals Master User Guide
29
Petals Master Runtime Management
7.6. Search Runtime Manager, Processor, Execution Environments and Environment Federations Petals Master GUI provides search interfaces for Runtime Manager, Processor, Execution Environement and Environment Federations. These search capabilities are similar to the other search capability of the Petals Master GUI.
Petals Master User Guide
30
Petals Master Web Services APIs
Chapter 8. Petals Master Web Services APIs Petals Master proposes two types of Web Services APIs : a UDDI V2/V3 compliant one and a Petals Master specific one. A list of all available WS APis available at : http://host:port/petals-master-${version-number}/ws
8.1. The UDDI WS API UDDI specification define two main sets of APIs : • Inquiry API that allows to locate and obtain detail on entries in a UDDI registry (Petals Master registry in our case). Petals Master fully implement this API for V2 and V3 UDDI specifications. Some findQualifiers aren't supported and the authentication part isn't implemented yet. • Publication API that allows to publish and update information contained in a UDDI registry. The publication API isn't implemented yet. Thank to this UDDI Inquiry API, Petals Master registry could be searched by UDDI V2/V3 compliant clients. For exemple, Eclipse IDE provides a built-in UDDI client based on UDDI V2 API, so you could search for services, organizations, and specifications from Eclipse development environment. Once Petals Master started, Petals Master UDDI Inquiry Web Services are available at : • Inquiry V2 : http://host:port/petals-master-${version-number}/ws/UddiInquiryServiceV2 • Inquiry V3 : http://host:port/petals-master-${version-number}/ws/UddiInquiryServiceV3 For more information about UDDI read the UDDI specification. For more information about Eclipse IDE UDDI client read the Eclipse documentation.
8.2. The Petals Master specific API Petals Master also provides its own Web Service API. This API allows to search entities in the Petals Master Registry but also to publish or update informations, to remove them, or to do more advanced stuff like linking entities (Person or Organization to Services or Endpoints...). Here is a list of all available services : • OrganizationManagerService : allows to search, retrieve, update and delete organizations and to manage posts linked to these organizations.
Note Available at : http://host:port/petals-master-${version-number}/ws/OrganizationManagerService • PersonManagerService : allows to search, retrieve, update and delete persons.
Note Available at : http://host:port/petals-master-${version-number}/ws/PersonManagerService • PostManagerService : allows to retrieve, update and delete posts.
Note Available at : http://host:port/petals-master-${version-number}/ws/PostManagerService
Petals Master User Guide
31
Petals Master Web Services APIs
• WSDLManagerService : allows to import new Services and Endpoints into Petals Master registry by providing their WSDL specifications or to retrieve WSDL specifications linked a given Service or Endpoint. Import and retrieval can be done with string or attached description (mtom ws attachment). Thanks to this API, you could import WSDL with absolute but also relative imports.
Note Available at : http://host:port/petals-master-${version-number}/ws/WSDLManagerService • ServiceManagerService : allows to search, retrieve, update and delete services and their related documents and categories.
Note Available at : http://host:port/petals-master-${version-number}/ws/ServiceManagerService • EndpointManagerService : allows to retrieve, update and delete services and their categories.
Note Available at : http://host:port/petals-master-${version-number}/ws/EndpointManagerService • RoleOfPartyManagerService : allows to create, retrieve or remove links between Services/Endpoints and Organizations/Persons.
Note Available at : http://host:port/petals-master-${version-number}/ws/RoleOfPartyManagerService • TechnologyManagerService : allows to synchronize and search information about service execution environment like Petals ESB.
Note Available at : http://host:port/petals-master-${version-number}/ws/TechnologyManagerService • TModelManagerService : allows to retrieve available categorization/identification systems and associated values for Organizations, Services and Endpoints.
Note Available at : http://host:port/petals-master-${version-number}/ws/TModelManagerService
Petals Master User Guide
32
Adding custom Category/Identifier systems for Organizations/Services/Endpoints
Chapter 9. Adding custom Category/Identifier systems for Organizations/Services/Endpoints Petals Master allows to add custom Category and Identifier systems for Organizations, Services and Endpoints to the registry at startup. Category and Identifier systems are called TModel in the UDDI taxonomy. A Category system is a set of category values that could be added to Organization, Service or Endpoint to classify it. Petals Master comes with a set of UDDI standard classification systems : NAICS 1997 and 2002, UNSPSC and ISO 3166 Codes for names of countries or regions. An Identifier system is a set of identifer values that uniquely identify an Organization in a specific identification system. If one of your organizations is identified in a specific identification system you could add this identifier in the registry through the UI or WS API. Petals Master comes with a set of UDDI standard identification systems : Dun and Bradstreet D-U-N-S Number and Thomas Registry Suppliers. Standard UDDI Category and Identifier systems are registered at Petals Master startup thanks to an XML dataset available in "${petals-master-root}/WEB-INF/classes/tmodel/" and called "base-tmodels.xml". You could add your custom Category and Identifier systems thanks to this file. Once added, they will be available in UI and WS API and then, they could be used with Services, Endpoints and Organizations.
Caution Don't remove standard TModels from "base-tmodels.xml". They are Petals Master requirements.
9.1. Adding custom categorisation system and associated values Here is a code snippet allowing to add a custom category to Petals Master registry at startup : - - - - - -My -Custom -Category - - - - - - - - - - - - - -Describe -my -custom -category - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -http://dragon.org/MyCustomCategoryFullDescription.txt - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -http://dragon.org/MyCustomCategory-valueSet.txt - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Petals Master User Guide
33
Adding custom Category/Identifier systems for Organizations/Services/Endpoints The tModel element : a category system is a TModel in UDDI taxonomy. You could specify a key for this TModel with the tModelKey attribute. If you don't specify any key, Petals Master will generate a key for you. Keys must have the following form "uddi:${root.domain}:anythingElse". For exemple, if the root domain specified in dragon.properties file is "mycompany.com", a valid key is "uddi:mycompany.com:foobar". If the key is generated by Petals Master, it will have the following form "uddi:${root.domain}:uuid" where uuid is an auto-generated unique identifier.
Caution if you specify your own keys, you're in charge of the unicity. The name element : the name of the category system. Will be used to represent the category system in UI. The description element : a human readable description of this category system. You could specify the language used for this description. Language is specified with a two letters country code as specified in the iso3166 specification. overviewDoc elements : they have two main purposes. A descriptive purpose. In this case, it will embed an overviewUrl element of useType "text", that point to a description URL. It will be used to provide a more detailed description of the category system. overviewDoc could also be used to specify a value set for this category system. In this case, it will embed an overviewUrl element of useType "valueSet", that point to a file listing all values and their related description. This value set file is a text file, each line is a "value" "description" couple separated by ";" character : value1;description -1 value2;description -2 value3;description -3 ...
The categoryBag element : used to classify the categorization system. The first keyedReference embeded element must be unchanged, it specifies that this tModel is a category tModel. The second one is optional but required if you have associated a value set to this category (using the overviewDoc element of useType "valueSet"). The last keyedReference embeded element is used to specified to which entities this categorization system applies (allowed keyValue attribute are, "all" to specify that this category applies to Organization, Services and Endpoint, "businessService" applies only to Services, "businessEntity" applies only to Organizations and "bindingTemplate" applies only to Endpoints.
9.2. Adding custom identification system Here is a code snippet allowing to add a custom identifier to Petals Master registry at startup : - - - - - -My -Custom -Identifier - - - - - - - - - - - - - -Describe -my -custom -identifier - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -http://dragon.org/MyCustomIdentifierFullDescription.txt - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
The tModel element : an identifier system is a TModel in UDDI taxonomy. You could specify a key for this TModel with the tModelKey attribute. If you don't specify any key, Petals Master will generate a key for you. Keys must have the following form "uddi:${root.domain}:anythingElse". For exemple, if the root domain specified in dragon.properties file is "mycompany.com", a valid key is "uddi:mycompany.com:foobar". If the key is generated by Petals Master, it will have the following form "uddi:${root.domain}:uuid" where uuid is an auto-generated unique identifier.
Petals Master User Guide
34
Adding custom Category/Identifier systems for Organizations/Services/Endpoints
Caution if you specify your own keys, you're in charge of the unicity. The name element : the name of the identifier system. Will be used to represent the identifier system in UI. The description element : a human readable description of this identifier system. You could specify the language used for this description. Language is specified with a two letters country code as specified in the iso3166 specification. overviewDoc elements : in the identifier case, they have only one main purpose, a descriptive purpose. In this case, it will embed an overviewUrl element of useType "text", that point to a description URL. It will be used to provide a more detailed description of the identifier system. The categoryBag element : used to classify the identifier system. The first keyedReference embeded element must be unchanged, it specifies that this tModel is a category tModel. The second one must be unchanged too because identifier tmodels only apply to Organizations.
Petals Master User Guide
35
