Author: deepal Date: Fri Feb 8 03:17:31 2008 New Revision: 13467 Log:
remote registry guide Added: branches/registry/1_0/modules/documentation/xdocs/remoteregistry.xml Added: branches/registry/1_0/modules/documentation/xdocs/remoteregistry.xml ============================================================================== --- (empty file) +++ branches/registry/1_0/modules/documentation/xdocs/remoteregistry.xml Fri Feb 8 03:17:31 2008 @@ -0,0 +1,306 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- + ~ Licensed to the Apache Software Foundation (ASF) under one + ~ or more contributor license agreements. See the NOTICE file + ~ distributed with this work for additional information + ~ regarding copyright ownership. The ASF licenses this file + ~ to you under the Apache License, Version 2.0 (the + ~ "License"); you may not use this file except in compliance + ~ with the License. You may obtain a copy of the License at + ~ + ~ http://www.apache.org/licenses/LICENSE-2.0 + ~ + ~ Unless required by applicable law or agreed to in writing, + ~ software distributed under the License is distributed on an + ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + ~ KIND, either express or implied. See the License for the + ~ specific language governing permissions and limitations + ~ under the License. + --> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";> +<?xml version="1.0" encoding="iso-8859-1"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" + "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd";> +<html xmlns="http://www.w3.org/1999/xhtml";> +<head> + <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" /> + <title>No title</title> + <meta name="generator" content="amaya 9.3, see http://www.w3.org/Amaya/"; /> +</head> + +<body> +<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> \ No newline at end of file _______________________________________________ Registry-dev mailing list [email protected] http://wso2.org/cgi-bin/mailman/listinfo/registry-dev
