Service Oriented Architecture is fundamentally based on metadata descriptions, schemas, URIs and policies. The key to a successful SOA deployment is to manage this data in a structured repository. WSO2 Registry is an open source product that enables you to store, catalog, index and manage your enterprise metadata in a simple, scalable and easy-to-use model. In fact, the WSO2 Registry can not only store such metadata but any other kind of data and maintain it in a versioned and URI-accessible manner. Think of the registry as a structured wiki designed to help you manage your metadata in a simple business-friendly system. Registry allows the storage of unstructured data such as Word documents, Excel spreadsheets and text formats. Using these approaches, you can build a catalog of services and service descriptions. A simple, RESTful programming API allows any and all resources stored in the WSO2 Registry to become a part of your dynamic SOA infrastructure- for example, by storing policies in the registry and using them for runtime policy enforcement. Built in community features allow WSO2 Registry users to comment on, tag and rate resources stored in the registry. Registry can be navigated using the given Web application, via an AtomPub API or via Java API (for both local and remote registries via AtomPub).
This document applies to version 0.1 of the WSO2 Registry.
Installing the WSO2 registry is a matter of copying wso2resgistry.war file into a servlet container such as Apache Tomcat. We recommend you use the latest version of Tomcat, version 6.* but it should work with version 5.*s as well. In Apache Tomcat, drop the .war file into webapps directory. (We assume that you have Java v1.5 at least.)
This initial release of WSO2 Registry only supports an unpacked (exploded) method of WAR deployment. Data you store in the registry will be saved in a database embedded in the WAR file and the files themselves will be located within the exploded WAR directory. Clearly, this is only used for reference - for if you want to add data, then you must configure an external data source or a JDBC connection as explained in the section below. If your application server does not automatically unpack the WAR file (e.g., JBossAS), then you must configure a data source to persist the data.
In both scenarios, you need to create database tables using scripts bundled in the source distribution. After deploying the .war file, start the application server, if it has not already.
Below are the steps for configuring WSO2 Registry with Apache Derby database.
<wso2regsitry>
<currentConfig>derby-db</currentConfig>
<dbconfig name="in-memory">
</dbconfig>
<dbconfig name="sample">
</dbconfig>
<dbconfig name="derby-db">
<url>jdbc:derby:/home/user1/wso2registry/db</url>
<userName>regadmin</userName>
<password>regadmin</password>
<driverName>org.apache.derby.jdbc.EmbeddedDriver</driverName>
</dbconfig>
......
......
</wso2registry>
11. Restart the servlet container. Now WSO2 Registry is running using the Apache Derby database!
After successfully deploying the WSO2 Registry webapp, launch a Web browser and point it to the the following URL:http://localhost:8080/wso2registry(you may need to change the port if your servlet runtime is listening on a different port).
This takes you to the welcome page of the registry console as given below:
Figure: Welcome page on WSO2 Registry's UI console
Note: By default the welcome screen displays the resources page of the root folder. Please Refer the 'Resources' section of this documentation for details on features provided on this page.
The option to sign in is available as a link on the top right hand corner of the welcome screen.
User will be logged in upon entering valid credentials.
The default system has an administrator configured with username/password combination as 'admin'/'admin'.
Navigation bar on the top right hand corner consists of the following options:
We will now discuss each of these menu options in detail:
This is the default option activated upon log-in.
In the left hand side column of the resources page you'll find three blocks, namely, Information, Entries and Permissions.
Information block includes details of a chosen resource including the creation date and time under the 'Created' label with 'Author' information, 'Last Updated' date and time with author information related to the update as 'By', link to different versions available through 'Versions' label and ratings for resources including current user rating and average rating. A 'Description' for the selected resource is also available.
Upon selecting "Edit Description" command button, an editor will be provided to insert a description for the chosen resource. Users can type a description and select the "Save" button to save updates.
Adding a resource could be done for a collection of resources or for an individual resource. To add a collection or directory, click on the button provided and a page will be presented to fill in the required information. Optionally, a description can be included for the resource in question.
Note : Adding and and deleting resources within the registry are considered version operations. Therefore, provision is made to rollback or restore a resource to any previous version. Refer Versions for additional information on this topic.
To delete a resource , click on the cylindric icon provided. However, upon doing so a resource will not be removed from the database but instead marked as deleted. This provides the opportunity to restore a previously deleted resource.
Using the 'entries' block, users are able to add additional resources and collections to the active folder.
To add a new resource:
1. Select the add resource icon provided on the top right hand corner of the entries block as illustrated in the diagram below
2. To add a file in the local machine as a resource, select "import content from file" option and browse and select the file. To import a remote resource, select the "Import content from URL" option and give the URL.
3. Change the name of the resource, media type and the description, if required.
4. Click "Add" button to add the new resource.
To add a new collection
1. Select the add collection icon in the entries block.
2. Type the name of the new collection.
3. Select a media type for the collection and type a description, if necessary. Note that the normal collections have the "default" media type.
4. Click "Add" button to add the new collection.
Using the following screen, WSO2 Registry permissions can be assigned to different roles and individual users.
The top half of the permission's screen is used to define user roles and the bottom half for defining role permissions.
To assign permissions to users or roles follow the steps given below:
1. select user/role from User/Role drop down
2. choose an action from the 'Action' drop down menu
3. select permission type. users are able to choose 'Allow' or 'Deny' by selecting appropriate option button.
4. Click 'Add Permission' to apply selection
Existing permissions can be changed by selecting and clearing the check boxes for required permissions and clicking the "Apply All Permissions" button.
Note: 'User permissions' have higher priority over 'role permissions'. 'Deny' permissions have higher priority over 'allow' priorities. Essentially, this means that permissions assigned to users overrides permissions assigned for a role and that a deny permission always overrides an 'allow' permission assigned to a user.
The right side of the resources page houses 3 additional blocks, namely: Tags, Comments and Versions.
Provides space to enter tags for a given resource. These tags can be used when searching for a resource as key words for search criteria.
Users can enter as many tags as they like provided individual tags are separated by commas and a given tag is not used by the same author to identify the same resource repeatedly.
Users can either comment or refer comments made by others using the comments block.
To add a new comment:
1. select the "ADD" icon located on the title of the bar of the comments block
2. enter comment in the text box provided
3. click the 'Add' button to continue.
Versions block provides version-specific information including different versions of a given resource. These include last modified date & time and By(username). Links are provided to visit a resource's specific version page, together with provision to rollback back to a chosen version of a resource.
Selecting "People" option on the navigation menu opens up the following screen. Authorized users could manage users and roles using options given.
A list of "users" with details including User name, Name and Action appears on the left side column of the window together with a list of "roles" including Role Name and Action available on the right side column.
"Username" column lists the username assigned for users with the "Name" column providing the friendly name. Under the "Actions" column action delete is indicated as an icon that provides the facility to delete chosen users from the users list.
To add new users:
1. select "Add New user" icon from the title bar of the users window
2. enter user details including Username, Password, Confirm Password and Role type in the space provided
3. upon completion selection a user role for the new user and click "Add" button to continue.
4. the newly created user will be listed as the last item in the users list.
Note:If an attempt is made by unauthorized users to create new users, the system will not allow this and will respond displaying the following error message: "User is unauthorized to perform the action". Sign in with valid credentials before attempting this activity.
Note:Icon next to add new user/add new role icon is an expand/collapse icon to switch between the two views.
The 'Activity' options presents the user with a search facility for searching activities performed on the Registry. The block titled "Search Activities" consists of space to enter search criteria such as Username, Path, Date and Filter by drop down in searching for recent activities. A screen shot of Search Activities block is given below. Notice the list of sample activities provided at the bottom of the block for the given Username.
This toggle option provides the ability to sign in into WSO2 registry or sign out of WSO2 Register, as needed.
WSO2 Registry can be embedded inside other Java applications as a library to provide resource/community oriented features. Once embedded, Java applications can access all the features of the registry using the Registry API (org.wso2.registry.Registry). If you want to use all the resource/community features (exposed in the WSO2 Registry web application), you should embed both WSO2 Registry and WSO2 User Manager libraries in your application. To start with, first place the WSO2 Registry jar and the WSO2 User Manager jar files in the class path of your application. There are many combinations in which you can use the embedded registry. We will discuss each scenario below.
You can just instantiate and use in-memory registry as shown below. In this mode, Registry uses an in-memory database and any data stored in the registry will not be persisted. Note that this mode is recommended only for testing and functional evaluation and not recommended for production deployments.
Registry registry = new InMemoryJDBCRegistry();
Now you can call API methods of the registry to access the registry features.
You can create a RegistryRealm and pass it to the constructor of the InMemoryRegistry to create a authorization aware registry. Note that it is highly recommended to use in-memory realm with the in-memory registry. Otherwise it may cause unexpected behaviors as only a part (users or resources) of the data get persisted.
Ream realm = new InMemoryRegistryRealm();
Registry registry = new InMemoryJDBCRegistry(realm);
Upon the instantiation of the RegistryRealm, registry user store will be populated with predefined set of users and permissions. Then you can create a SecureRegistry instance for the admin user (pre-populated) and use it to add initial set of users and resources to the registry.
SecureRegistry adminRegistry = new SecureRegistry("admin", "admin", registry, realm);
Use the realm of the adminRegistry to add initial set of user, roles and permissions.
Realm adminRealm = adminRegistry.getUserRealm();
Once all initial users/resources are added, you can create SecureRegistry instances for each user and use those instances to access the registry. When the registry is accessed via a SecureRegistry instance, all the actions are authorized. That is, only the actions permitted for the user of the SecureRegistry are allowed.
If a DataSource is available for your application, you can simply create a non-secure persistence registry by providing a DataSource instance for the JDBCRegistry constructor.
Registry registry = new JDBCRegistry(datasource);
If a DataSource is not available, you can use the RegistryDataSource constructed using database attributes.
DataSource datasource = new RegistryDataSource("jdbc:derby:/home/reguser/db/registryDB", "org.apache.derby.jdbc.EmbeddedDriver", "user1", "user1password");Registry registry = new JDBCRegistry(datasource);
Now you can use this registry instance as before. All your data will be persisted to the given database.
First create a persistence realm using a datasource.
Realm realm = new RegistryRealm(datasource);
Then create a JDBCRegistry instance using the above realm and a datasource.
Registry registry = new JDBCRegistry(datasource, realm);
Then you can create SecureRegistry instances and access the registry with authorizations as mentioned in the second scenario. All your data about the resources and users will be persisted to the given database.