Author: glen
Date: Tue Feb 5 13:36:50 2008
New Revision: 13290
Log:
Some JavaDoc improvements
Modified:
trunk/registry/modules/core/src/main/java/org/wso2/registry/CoreRegistry.java
trunk/registry/modules/core/src/main/java/org/wso2/registry/Registry.java
Modified:
trunk/registry/modules/core/src/main/java/org/wso2/registry/CoreRegistry.java
==============================================================================
---
trunk/registry/modules/core/src/main/java/org/wso2/registry/CoreRegistry.java
(original)
+++
trunk/registry/modules/core/src/main/java/org/wso2/registry/CoreRegistry.java
Tue Feb 5 13:36:50 2008
@@ -15,9 +15,19 @@
*/
package org.wso2.registry;
+/**
+ * CoreRegistry is the central get/put API for the Registry. This is
typically what you want
+ * if you're a Java programmer wanting to simply store and manage Resources.
Since it's an
+ * interface, you don't care if the results come from (say) an embedded
file-based Registry or
+ * a remote one - that decision (and the resulting cache dynamics, exception
throwing, etc)
+ * can be made by a factory or dependency injection.
+ *
+ * If you want programatic access to features like
tags/comments/ratings/versions, please
+ * have a look at the full Registry interface which extends this one.
+ */
public interface CoreRegistry {
/**
- * Returns the resource in the given path.
+ * Returns the resource at the given path.
*
* @param path Path of the resource. e.g. /project1/server/deployment.xml
* @return Resource instance
@@ -27,18 +37,18 @@
Resource get(String path) throws RegistryException;
/**
- * Check whether a resource exist in the given path
+ * Check whether a resource exists at the given path
*
* @param path Path of the resource to be checked
- * @return true if a resource exist in the given path, false otherwise.
+ * @return true if a resource exists at the given path, false otherwise.
* @throws org.wso2.registry.RegistryException
* if an error occurs
*/
boolean resourceExists(String path) throws RegistryException;
/**
- * Adds or updates resources in the registry. If there is no resource in
the given path,
- * resource is added. If a resource already exist in the given path, it
will be replaced with
+ * Adds or updates resources in the registry. If there is no resource at
the given path,
+ * resource is added. If a resource already exist at the given path, it
will be replaced with
* the new resource.
*
* @param suggestedPath the path which we'd like to use for the new
resource.
@@ -50,7 +60,7 @@
String put(String suggestedPath, Resource resource) throws
RegistryException;
/**
- * Deletes the resource in the given path. If the path refers to a
directory, all child
+ * Deletes the resource at the given path. If the path refers to a
directory, all child
* resources of the directory will also be deleted.
*
* @param path Path of the resource to be deleted.
Modified:
trunk/registry/modules/core/src/main/java/org/wso2/registry/Registry.java
==============================================================================
--- trunk/registry/modules/core/src/main/java/org/wso2/registry/Registry.java
(original)
+++ trunk/registry/modules/core/src/main/java/org/wso2/registry/Registry.java
Tue Feb 5 13:36:50 2008
@@ -22,7 +22,10 @@
import java.util.Date;
import java.util.Map;
-/** API for the Registry. Java applications should use this API to access the
registry. */
+/**
+ * This is the "Full" Registry interface. It contains not only the get/put
behavior from
+ * CoreRegistry, but also APIs which control
tags/comments/ratings/versions/etc.
+ */
public interface Registry extends CoreRegistry {
/**
@@ -30,39 +33,30 @@
*
* @param suggestedPath path where we'd like to add the new resource.
Although this path is
* specified by the caller of the method, resource
may not be actually
- * added to this path.
+ * added at this path.
* @param sourceURL where to fetch the resource content
* @param metadata a template Resource
- * @return actual path to which the resource is added
- * @throws RegistryException
+ * @return actual path to the new resource
+ * @throws RegistryException if we couldn't get or store the new resource
*/
String importResource(String suggestedPath,
String sourceURL,
Resource metadata) throws RegistryException;
/**
- * Deletes the resource in the given path. If the path refers to a
directory, all child
- * resources of the directory will also be deleted.
- *
- * @param path Path of the resource to be deleted.
- * @throws org.wso2.registry.RegistryException
- * is thrown depending on the implementation.
- */
- void delete(String path) throws RegistryException;
-
- /**
* Move or rename a resource in the registry. This is equivalent to 1)
delete the resource,
- * then 2) add the resource to the new location.
+ * then 2) add the resource to the new location. The operation is atomic,
so if it fails
+ * the old resource will still be there.
*
* @param currentPath current path of the resource
* @param newPath where we'd like to move the reosurce
* @return the actual path for the new resource
- * @throws RegistryException : If something went wrong
+ * @throws RegistryException if something went wrong
*/
String rename(String currentPath, String newPath) throws RegistryException;
/**
- * Returns the paths of the versions of the resource located at the given
path. Version paths
+ * Get a list of all versions of the resource located at the given path.
Version paths
* are returned in the form /projects/myresource?v=12
*
* @param path path of a current version of a resource
_______________________________________________
Registry-dev mailing list
[email protected]
http://wso2.org/cgi-bin/mailman/listinfo/registry-dev
