Author: chathura Date: Sat Feb 9 23:45:06 2008 New Revision: 13506 Log:
Combined the remote registry guide to the user guide. Modified: trunk/registry/modules/documentation/xdocs/userguide.xml Modified: trunk/registry/modules/documentation/xdocs/userguide.xml ============================================================================== --- trunk/registry/modules/documentation/xdocs/userguide.xml (original) +++ trunk/registry/modules/documentation/xdocs/userguide.xml Sat Feb 9 23:45:06 2008 @@ -161,7 +161,7 @@ below:</p> <p></p> - +<img src="../resources/images/image1.jpg" alt="Registry console - welcome page"/> <p></p> <p>Figure: Welcome page on WSO2 Registry's UI console</p> @@ -181,7 +181,7 @@ <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><img src="../resources/images/image3.jpg" alt="Registry console - login screen"/></p> <p>User will be logged in upon entering valid credentials.</p> @@ -292,7 +292,7 @@ <p>4. Click "Add" button to add the new collection.</p> -<p></p> +<p><img src="../resources/images/entries.png" alt="Registry console - Entries view"/></p> <h4>Permissions</h4> @@ -302,7 +302,7 @@ <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><img src="../resources/images/permissions.png" alt="Registry console - Permissions view"/></p> <p>To assign permissions to users or roles follow the steps given below:</p> @@ -347,7 +347,7 @@ separated by commas and a given tag is not used by the same author to identify the same resource repeatedly.</p> -<p></p> +<p><img src="../resources/images/image6.jpg" alt="Registry console - Tags"/></p> <h4>Comments</h4> @@ -365,7 +365,7 @@ <p>3. click the 'Add' button to continue.</p> -<p></p> +<p><img src="../resources/images/image5.jpg" alt="Registry console - Comments"/></p> <h4>Versions</h4> @@ -375,13 +375,15 @@ together with provision to rollback back to a chosen version of a resource.</p> -<p></p> +<p><img src="../resources/images/image7.jpg" alt="Registry console - Versions view"/></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><img src="../resources/images/Image9.jpg" alt="Registry console - People"/></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> @@ -413,7 +415,7 @@ message: "User is unauthorized to perform the action". Sign in with valid credentials before attempting this activity.</p> -<p></p> +<p><img src="../resources/images/Imageq10.jpg" alt="Registry console - Roles"/></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> @@ -430,7 +432,7 @@ sample activities provided at the bottom of the block for the given Username.</p> -<p></p> +<p><img src="../resources/images/Recent Activitivity.png" alt="Registry console - Recent Activity"/></p> <h2>Sign In/Out:</h2> @@ -566,5 +568,278 @@ <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> + +<h2>RemoteRegistry</h2> + +<p>In simple words, the RemoteRegistry is a Java API for interacting with a +Registry instance. Regardless of where a given Registry instance is located, +either locally or remotely, we can still talk to it using RemoteRegistry. The +RemoteRegistry is yet another implementation of org.wso2.registry.Registry +interface. However, the difference between the RemoteRegistry and a standard +Registry is that, the RemoteRegistry is not an actual registry but a client +for interacting with a registry instance.</p> + +<p>Communication between the Registry and the RemoteRegistry takes place +using the Atom Publishing Protocol (APP). When we deploy registry files +(registry.war) in an application server, an atom feed is generated . +Thereafter, if you browse http://localhost:8080/wso2registry/atom (this +address changes depending on your application server settings), you'd be able +to see the atom feed from the registry. The structure and format of the feed +is described in the following location: +http://www.wso2.org/wiki/display/registry/Registry+Protocol.</p> + +<p></p> + +<h3>How to Create an Instance of the RemoteRegistry</h3> + +<p>To create an instance of the RemoteRegistry, what we need first is the URL +of a registry. If the root of the registry is http://foo.com/, the URL for +the RemoteRegistry instance would be http://foo.com/atom. Once we have the +URL figured out, we can create an instance of the RemoteRegistry using the +following code:</p> + +<p></p> + +<pre><code>RemoteRegistry remote_registry = new RemoteRegistry(new +URL("http://localhost:8080/wso2registry/atom";));</code></pre> + +<p>Creating an instance of the RemoteRegistry in this manner, is similar to +accessing a registry without login into it with communication taking place as +an anonymous user.</p> + +<p>If you have a user name and password for the registry, you can pass them +along when creating the remote_registry instance. At that point, all +permissions granted for the particular username/password pair will apply to +the owner of the remote_registry instance. Creating the remote_registry with +user name and the password can be done using:</p> + +<pre><code>RemoteRegistry remote_registry = new RemoteRegistry(new +URL("http://localhost:8080/wso2registry/atom";), "admin", "admin");</code></pre> + +<p>In this example, we have created the remote_registry instance with +username=”admin” and the password as also “admin”.</p> + +<h3>Reading a resource</h3> + +<p>Once we have the registry instance in place, navigation is +straightforward. It is the same as working with the Registry API. Say we have +a resource called “/foo/c1” in the Registry and you can access it +using the remote_registry instance as given below:</p> + +<p></p> + +<pre><code>Resource resource = remote_registry.get("/foo/c1");</code></pre> + +<p></p> + +<p>The resource object will represent the actual resource object in the +Registry. But if the resource is a collection, then the object will, of +course, represent the collection.</p> + +<p>As you can see in the code sample above, once we have a remote_registry +instance we do not need to pass a complete URL for all invocations. It is +adequate to pass only a relative path to a resource.</p> + +<h3>Adding a Resource</h3> + +<p>To add a resource to the remote_registry instance, first thing we need to +do is to create a Resource object and then to call its put method:</p> + +<p>First let's try to cerate a collection called “/foo/c2”</p> + +<p></p> + +<pre><code>Resource resource = new Resource(); + +remote_registry.put("resource", resource);</code></pre> + +<p>If you call the get method then you'd be able to access that resource +created.</p> + +<p>Now let's try to add a resource with content. For that, we need to first +create a Resource object and then set content.</p> + +<p></p> + +<pre><code>Resource r1 = new Resource(); + +String str = "My Content"; + +r1.setContent(str.getBytes()); + +remote_registry.put("/c1/c2/r1", r1);</code></pre> + +<p></p> + +<h3>Checking for the Existence of a Resource</h3> + +<p>We can use the following code to confirm whether the resource exists:</p> + +<pre>boolean value =remote_registry.resourceExists(“/c1/c2/r1”);</pre> + +<p>If the resource does exist, a boolean value of true will be returned, else +false.</p> + +<h3>Deleting a Resource</h3> + +<p>Additionally, we can use the remote_registry instance to delete resources. +Deleting a resource is a matter of calling the delete method of the +remote_registry. Let's just say we want to delete “/c1/c2/r1”. +Then we can use the following code:</p> + +<pre>RemoteRegistry.delete(“/c1/c2/r1”);</pre> + +<p></p> + +<h3>Renaming a resource</h3> + +<p>We can rename individual resources but but we cannot rename collections. +To rename a resource, use the following lines of code.</p> + +<p></p> + +<pre>remote_registry.rename(“/c1/c2/r1” , +“/c1/c2/r2”);</pre> + +<p>Above line of code renames ““/c1/c2/r1”” to +“/c1/c2/r2”</p> + +<p></p> + +<p>Retrieving different Versions of a Given Resource</p> + +<p>We can list all of the versions of a given resource using the code given +below. The result would be an array of String, containing links to the +different versions of the resource.</p> + +<pre>String [] versions = remote_registry.getVersions(“/c1/c2”);</pre> + +<h3>Restoring to an old version</h3> + +<p>Since the Registry comes with versioning, we can restore a resource to any +of its versions. This can be done using the remote_registry as well. In the +previous section, we discussed how to retrieve versions for a give resource. +The following line of code demonstrates we can restore back an old version of +the remote_registry instance.</p> + +<p></p> + +<pre>remote_registry.restoreVersion (versions[2]);</pre> + +<h3></h3> + +<h3>Adding a Tag</h3> + +<p>We can perform tagging operations using the remote_registry. To tag a +resource, we need the resource path and the tagging words. Let's say we need +to tag a resource named “/c1/c2/r2” as “rename +resource”. We can do this as:</p> + +<pre>remote_registry.applyTag(“/c1/c2/r2” , “rename +resource”);</pre> + +<p></p> + +<h3>Retrieving All Tags of a Given Resource</h3> + +<p>We can use the remote_registry to retrieve tags for a give resource. It +will return an array of Tag type and we can iterate the array to see the +content.</p> + +<pre>Tag[] tags = remote_registry.getTags(“/c1/c2/r2”);</pre> + +<h3>Deleting a Tag</h3> + +<p>We can remove a tag using the tag name. Use the following code:</p> + +<pre>remote_registry.removeTag(“/c1/c2/r2”,“rename +resource”);</pre> + +<h3>Commenting a Resource</h3> + +<p>We can also comment on a resource using the remote_registry. Here, we will +create a comment object and call the remote_registry instance. Following +lines of code illustrates how we can achieve this:</p> + +<p></p> + +<pre><code>Comment c1 = new Comment(); + +c1.setText("This is my comment"); + +String commentpath = remote_registry.addComment("/c1/c2/r2", c1);</code></pre> + +<p></p> + +<p>The above lines of code will add a comment to the resource named: +“c1/c2/r2 “.</p> + +<h3>Edit a Comment</h3> + +<p>We can also make changes to comments we have already made using the +remote_registry instance. Here, we need the path and new text for the comment +we are adding. Say we want to change from “This is my comment” to +“This is cool”, For that, we can do the following:</p> + +<pre>remote_registry.editComment(commentpath,“This is cool”)</pre> + +<h3>Rating a Resource</h3> + +<p>In order to rate a resource based on our judgment, we can again use the +remote_registry instance. Rating a resource can be done using following line +of code:</p> + +<pre>remote_registry.rateResource(“c1/c2/r2 ” , 4);</pre> + +<p>In addition to the above operations, there are a number of others that we +can perform using the remote_registry instance. In this document we have +discussed only the most commonly used operations.</p> + +<h2>Importing the Local File System to the Registry</h2> + +<p>We can use the RemoteRegistry to export our entire local file system into +the Registry. What we need to do is to give the location of the file system +and the location where we want to put them in the Registry. Once we do that, +inside the registry it will create the same structure as the file system and +upload all files into the Registry. We can consider this as any check-in +operation on any kind of version management system. Following code +demonstrates how to import a local file system into the Registry:</p> + +<p>File file = new File(“Path of the file”);</p> + +<pre><code>RemoteRegistry remote_registry = new RemoteRegistry(new +URL("http://localhost:8080/wso2registry/atom";), "admin", "admin"); + +RegistryClientUtils.importToRegistry(file , +“/myfile/filesystem” ,remote_registry);</code></pre> + +<p></p> + +<h2>Exporting the Registry to a File System</h2> + +<p>In the previous section, we discussed how to import a local file system +into the Registry. There is another way round of this and it is to check-out +the Registry to a local file system. To export, we can select either the +entire Registry or a selected node. Depending on the node we select, the +remote_registry instance will create the same structure within the file +system. Even if we have the resource with binary data, then it will create +all of the necessary files in the file system.</p> + +<p>Let's say we want to export “/myfile/filesystem” into my local +file system then we can use the following code:</p> + +<pre><code>File toFile = new File(“Path of the new file”); + +RemoteRegistry remote_registry = new RemoteRegistry(new +URL("http://localhost:8080/wso2registry/atom";), "admin", "admin"); + +RegistryClientUtils.importToRegistry( toFile, +“/myfile/filesystem” ,remote_registry);</code></pre> + +<p></p> + +<p>We need to keep in mind when exporting the Registry to a file system, that +it will only export the resources but not the comments, tags and any rating +associated.</p> </body> </html> _______________________________________________ Registry-dev mailing list [email protected] http://wso2.org/cgi-bin/mailman/listinfo/registry-dev
