Author: chathura Date: Fri Feb 8 04:04:35 2008 New Revision: 13476 Log:
Added the new user guide. Added: branches/registry/1_0/modules/documentation/xdocs/userguide.xml Added: branches/registry/1_0/modules/documentation/xdocs/userguide.xml ============================================================================== --- (empty file) +++ branches/registry/1_0/modules/documentation/xdocs/userguide.xml Fri Feb 8 04:04:35 2008 @@ -0,0 +1,570 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";> +<html xmlns="http://www.w3.org/1999/xhtml";> +<head> + <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" /> + <title>WSO2 Registry - User Guide</title> + <meta name="generator" content="Amaya 9.54, see http://www.w3.org/Amaya/"; /> +</head> + +<body> +<h1>Introduction</h1> + +<p></p> + +<p>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).</p> + +<p></p> + +<p>This document applies to version 0.1 of the WSO2 Registry.</p> + +<p></p> + +<h1>Installing the WSO2 Registry</h1> + +<p></p> + +<p>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.)</p> + +<p></p> + +<p>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.</p> + +<p></p> + +<h2>Configuring a Data Source or Database</h2> +<ul> + <li>Configure a data source in the application sever and edit the + WEB-INF/registry.xml by adding a database configuration with the data + source name.</li> + <li>Configure a database using connection parameters (connection URL, + driver class name, user name, password) in the registry.xml file.</li> +</ul> + +<p>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.</p> + +<p></p> + +<h4>Configuring the WSO2 Registry to work with Apache Derby</h4> + +<p></p> + +<p>Below are the steps for configuring WSO2 Registry with Apache Derby +database.</p> + +<p></p> +<ol> + <li>Download and install Apache Derby in you computer, if it is not already + done.</li> + <li>Goto the <derby-installation directory>/bin directory and run the + derby network server starting script. Usually this is named as + "startNetworkServer".</li> + <li>Open another console and run the ij tool located in the + <derby-installation directory>/bin directory.</li> + <li>Create the registry database and connect to it using the following + command inside the ij prompt (replace the database file path, user name + and password in below command to suite your requirements). + <p>connect + 'jdbc:derby:/home/user1/wso2registry/db;user=regadmin;password=regadmin;create=true'</p> + </li> + <li>Run the derby script provided with the WSO2 Registry using the below + command (this will create all necessary tables for the WSO2 Registry and + the WSO2 User Manager embedded inside the Registry). + <p>run '/home/user1/wso2registry/derby-complete.sql';</p> + </li> + <li>Verify whether all the tables are created by using the below command. + <p>show tables;</p> + </li> + <li>Exit the ij command using the exit command. + <p>exit;</p> + </li> + <li>Place the derbyclient.jar in the class path of the WSO2 Registry web + application.</li> + <li>Edit the registry.xml file of the deployed registry instance as below + (note the highlighted configurations).</li> +</ol> + +<p></p> +<pre><wso2regsitry></pre> +<pre></pre> +<pre><currentConfig>derby-db</currentConfig></pre> +<pre></pre> +<pre><dbconfig name="in-memory"></pre> +<pre></dbconfig></pre> +<pre></pre> +<pre><dbconfig name="sample"></pre> +<pre></dbconfig></pre> +<pre></pre> +<pre><dbconfig name="derby-db"></pre> +<pre><url>jdbc:derby:/home/user1/wso2registry/db</url></pre> +<pre><userName>regadmin</userName></pre> +<pre><password>regadmin</password></pre> +<pre><driverName>org.apache.derby.jdbc.EmbeddedDriver</driverName></pre> +<pre></dbconfig></pre> +<pre></pre> +<pre>......</pre> +<pre></pre> +<pre>......</pre> +<pre></pre> +<pre></wso2registry></pre> + +<p></p> + +<p>11. Restart the servlet container. Now WSO2 Registry is running using the +Apache Derby database!</p> + +<p></p> + +<h2>Welcome Page</h2> + +<p></p> + +<p>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).</p> + +<p></p> + +<p>This takes you to the welcome page of the registry console as given +below:</p> + +<p></p> + +<p></p> + +<p>Figure: Welcome page on WSO2 Registry's UI console</p> + +<p></p> + +<p>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.</p> + +<p></p> + +<h2>Signing into WSO2 Registry</h2> + +<p></p> + +<p>The option to sign in is available as a link on the top right hand corner +of the welcome screen.</p> + +<p></p> + +<p>User will be logged in upon entering valid credentials.</p> + +<p>The default system has an administrator configured with username/password +combination as 'admin'/'admin'.</p> + +<p></p> + +<h3>Navigation Bar</h3> + +<p>Navigation bar on the top right hand corner consists of the following +options:</p> +<ul> + <li>Resources</li> + <li>People</li> + <li>Activity</li> + <li>Sign in</li> +</ul> + +<p>We will now discuss each of these menu options in detail:</p> + +<p></p> + +<h3>Resources</h3> + +<p>This is the default option activated upon log-in.</p> + +<p></p> + +<p>In the left hand side column of the resources page you'll find three +blocks, namely, Information, Entries and Permissions.</p> + +<p></p> + +<h4>Information</h4> + +<p>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.</p> + +<p>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.</p> + +<p></p> + +<h5>Adding a new Resource</h5> + +<p>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.</p> + +<p></p> + +<p>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.</p> + +<p></p> + +<h5>Deleting a Resource</h5> + +<p>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.</p> + +<p></p> + +<h4>Entries</h4> + +<p>Using the 'entries' block, users are able to add additional resources and +collections to the active folder.</p> + +<p>To add a new resource:</p> + +<p></p> + +<p>1. Select the add resource icon provided on the top right hand corner of +the entries block as illustrated in the diagram below</p> + +<p>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.</p> + +<p>3. Change the name of the resource, media type and the description, if +required.</p> + +<p>4. Click "Add" button to add the new resource.</p> + +<p></p> + +<p>To add a new collection</p> + +<p></p> + +<p>1. Select the add collection icon in the entries block.</p> + +<p>2. Type the name of the new collection.</p> + +<p>3. Select a media type for the collection and type a description, if +necessary. Note that the normal collections have the "default" media type.</p> + +<p>4. Click "Add" button to add the new collection.</p> + +<p></p> + +<h4>Permissions</h4> + +<p>Using the following screen, WSO2 Registry permissions can be assigned to +different roles and individual users.</p> + +<p>The top half of the permission's screen is used to define user roles and +the bottom half for defining role permissions.</p> + +<p></p> + +<p>To assign permissions to users or roles follow the steps given below:</p> + +<p></p> + +<p>1. select user/role from User/Role drop down</p> + +<p>2. choose an action from the 'Action' drop down menu</p> + +<p>3. select permission type. users are able to choose 'Allow' or 'Deny' by +selecting appropriate option button.</p> + +<p>4. Click 'Add Permission' to apply selection</p> + +<p></p> + +<p>Existing permissions can be changed by selecting and clearing the check +boxes for required permissions and clicking the "Apply All Permissions" +button.</p> + +<p></p> + +<p>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.</p> + +<p></p> + +<p>The right side of the resources page houses 3 additional blocks, namely: +Tags, Comments and Versions.</p> + +<p></p> + +<h4>Tags</h4> + +<p>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.</p> + +<p>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.</p> + +<p></p> + +<h4>Comments</h4> + +<p>Users can either comment or refer comments made by others using the +comments block.</p> + +<p>To add a new comment:</p> + +<p></p> + +<p>1. select the "ADD" icon located on the title of the bar of the comments +block</p> + +<p>2. enter comment in the text box provided</p> + +<p>3. click the 'Add' button to continue.</p> + +<p></p> + +<h4>Versions</h4> + +<p>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.</p> + +<p></p> + +<h2>People</h2> + +<p>Selecting "People" option on the navigation menu opens up the following +screen. Authorized users could manage users and roles using options given.</p> + +<p>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.</p> + +<p>"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.</p> + +<p></p> + +<p>To add new users:</p> + +<p>1. select "Add New user" icon from the title bar of the users window</p> + +<p>2. enter user details including Username, Password, Confirm Password and +Role type in the space provided</p> + +<p>3. upon completion selection a user role for the new user and click "Add" +button to continue.</p> + +<p>4. the newly created user will be listed as the last item in the users +list.</p> + +<p></p> + +<p>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.</p> + +<p></p> + +<p>Note:Icon next to add new user/add new role icon is an expand/collapse +icon to switch between the two views.</p> + +<p></p> + +<h2>Activity</h2> + +<p>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.</p> + +<p></p> + +<h2>Sign In/Out:</h2> + +<p>This toggle option provides the ability to sign in into WSO2 registry or +sign out of WSO2 Register, as needed.</p> + +<p></p> + +<h1>Embedding the WSO2 Registry</h1> + +<p></p> + +<p>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.</p> + +<p></p> + +<h3>Creating an in-memory Registry without authorizations</h3> + +<p>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.</p> + +<p></p> +<pre>Registry registry = new InMemoryJDBCRegistry();</pre> + +<p></p> + +<p>Now you can call API methods of the registry to access the registry +features.</p> + +<p></p> + +<h3>Creating an in-memory Registry with authorizations</h3> + +<p>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.</p> + +<p></p> +<pre>Ream realm = new InMemoryRegistryRealm();</pre> +<pre>Registry registry = new InMemoryJDBCRegistry(realm);</pre> + +<p></p> + +<p>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.</p> + +<p></p> +<pre>SecureRegistry adminRegistry = new SecureRegistry("admin", "admin", registry, realm);</pre> + +<p></p> + +<p>Use the realm of the adminRegistry to add initial set of user, roles and +permissions.</p> + +<p></p> +<pre>Realm adminRealm = adminRegistry.getUserRealm();</pre> + +<p></p> + +<p>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.</p> + +<p></p> + +<h3>Creating a persistence Registry without authorizations</h3> + +<p></p> + +<p>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.</p> + +<p></p> +<pre>Registry registry = new JDBCRegistry(datasource);</pre> + +<p></p> + +<p></p> + +<p>If a DataSource is not available, you can use the RegistryDataSource +constructed using database attributes.</p> + +<p></p> +<pre>DataSource datasource = new RegistryDataSource("jdbc:derby:/home/reguser/db/registryDB", "org.apache.derby.jdbc.EmbeddedDriver", "user1", "user1password");</pre> +<pre></pre> +<pre>Registry registry = new JDBCRegistry(datasource);</pre> + +<p></p> + +<p>Now you can use this registry instance as before. All your data will be +persisted to the given database.</p> + +<p></p> + +<h3>Creating a persistence Registry with authorizations</h3> + +<p></p> + +<p>First create a persistence realm using a datasource.</p> + +<p></p> +<pre>Realm realm = new RegistryRealm(datasource);</pre> + +<p></p> + +<p>Then create a JDBCRegistry instance using the above realm and a +datasource.</p> + +<p></p> +<pre>Registry registry = new JDBCRegistry(datasource, realm);</pre> + +<p></p> + +<p>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. </p> +</body> +</html> _______________________________________________ Registry-dev mailing list [email protected] http://wso2.org/cgi-bin/mailman/listinfo/registry-dev
