Added javadocs

5 files changed, 45 insertions, 19 deletions

diff --git a/framework/bundles/org.eclipse.ecf.storage/src/org/eclipse/ecf/internal/storage/ContainerEntry.java b/framework/bundles/org.eclipse.ecf.storage/src/org/eclipse/ecf/internal/storage/ContainerEntry.java
index f4ed8bebf..1ae1a9f43 100644
--- a/framework/bundles/org.eclipse.ecf.storage/src/org/eclipse/ecf/internal/storage/ContainerEntry.java
+++ b/framework/bundles/org.eclipse.ecf.storage/src/org/eclipse/ecf/internal/storage/ContainerEntry.java
@@ -47,7 +47,7 @@ public class ContainerEntry implements IContainerEntry {
 			IContainer container = ContainerFactory.getDefault().createContainer(getFactoryName(), getContainerID());
 			IStorableContainerAdapter containerAdapter = (IStorableContainerAdapter) container.getAdapter(IStorableContainerAdapter.class);
 			if (containerAdapter != null) {
-				containerAdapter.handleRestore(prefs);
+				containerAdapter.restore(prefs);
 			}
 			return container;
 		} catch (IDCreateException e) {
diff --git a/framework/bundles/org.eclipse.ecf.storage/src/org/eclipse/ecf/internal/storage/ContainerStore.java b/framework/bundles/org.eclipse.ecf.storage/src/org/eclipse/ecf/internal/storage/ContainerStore.java
index a3932867e..5833401ee 100644
--- a/framework/bundles/org.eclipse.ecf.storage/src/org/eclipse/ecf/internal/storage/ContainerStore.java
+++ b/framework/bundles/org.eclipse.ecf.storage/src/org/eclipse/ecf/internal/storage/ContainerStore.java
@@ -56,21 +56,21 @@ public class ContainerStore implements IContainerStore {
 	/* (non-Javadoc)
 	 * @see org.eclipse.ecf.storage.IContainerStore#store(org.eclipse.ecf.storage.IStorableContainerAdapter)
 	 */
-	public IContainerEntry store(IStorableContainerAdapter containerAdapter) {
-		String factoryName = containerAdapter.getFactoryName();
+	public IContainerEntry store(IStorableContainerAdapter containerAdapter) throws StorageException {
+		String factoryName = containerAdapter.getContainerFactoryName();
 		Assert.isNotNull(factoryName);
 		ID containerID = containerAdapter.getID();
 		Assert.isNotNull(containerID);
 		IIDEntry idEntry = idStore.store(containerID);
 		ContainerEntry containerEntry = new ContainerEntry(idEntry);
 		try {
-			containerEntry.setFactoryName(containerAdapter.getFactoryName(), containerAdapter.encrypt());
-			containerAdapter.handleStore(containerEntry.getPreferences());
+			containerEntry.setFactoryName(containerAdapter.getContainerFactoryName(), containerAdapter.storeEncrypted());
+			containerAdapter.store(containerEntry.getPreferences());
 			return containerEntry;
 		} catch (StorageException e) {
 			// Undo and return null
 			containerEntry.delete();
-			return null;
+			throw e;
 		}
 	}
 
diff --git a/framework/bundles/org.eclipse.ecf.storage/src/org/eclipse/ecf/internal/storage/StorableBaseContainer.java b/framework/bundles/org.eclipse.ecf.storage/src/org/eclipse/ecf/internal/storage/StorableBaseContainer.java
index 0d68672bc..4d0904ef5 100644
--- a/framework/bundles/org.eclipse.ecf.storage/src/org/eclipse/ecf/internal/storage/StorableBaseContainer.java
+++ b/framework/bundles/org.eclipse.ecf.storage/src/org/eclipse/ecf/internal/storage/StorableBaseContainer.java
@@ -41,28 +41,28 @@ public class StorableBaseContainer extends BaseContainer implements IStorableCon
 	/* (non-Javadoc)
 	 * @see org.eclipse.ecf.storage.IStorableContainerAdapter#encrypt()
 	 */
-	public boolean encrypt() {
+	public boolean storeEncrypted() {
 		return false;
 	}
 
 	/* (non-Javadoc)
 	 * @see org.eclipse.ecf.storage.IStorableContainerAdapter#getFactoryName()
 	 */
-	public String getFactoryName() {
+	public String getContainerFactoryName() {
 		return "ecf.storage.basecontainer"; //$NON-NLS-1$
 	}
 
 	/* (non-Javadoc)
 	 * @see org.eclipse.ecf.storage.IStorableContainerAdapter#handleRestore(org.eclipse.equinox.security.storage.ISecurePreferences)
 	 */
-	public void handleRestore(ISecurePreferences prefs) throws StorageException {
+	public void restore(ISecurePreferences prefs) throws StorageException {
 		System.out.println("handleRestore(" + prefs + ")"); //$NON-NLS-1$ //$NON-NLS-2$
 	}
 
 	/* (non-Javadoc)
 	 * @see org.eclipse.ecf.storage.IStorableContainerAdapter#handleStore(org.eclipse.equinox.security.storage.ISecurePreferences)
 	 */
-	public void handleStore(ISecurePreferences prefs) throws StorageException {
+	public void store(ISecurePreferences prefs) throws StorageException {
 		System.out.println("handleStore(" + prefs + ")"); //$NON-NLS-1$ //$NON-NLS-2$
 	}
 
diff --git a/framework/bundles/org.eclipse.ecf.storage/src/org/eclipse/ecf/storage/IContainerStore.java b/framework/bundles/org.eclipse.ecf.storage/src/org/eclipse/ecf/storage/IContainerStore.java
index 2e7ec904f..2d6da15dc 100644
--- a/framework/bundles/org.eclipse.ecf.storage/src/org/eclipse/ecf/storage/IContainerStore.java
+++ b/framework/bundles/org.eclipse.ecf.storage/src/org/eclipse/ecf/storage/IContainerStore.java
@@ -13,6 +13,7 @@ package org.eclipse.ecf.storage;
 
 import org.eclipse.core.runtime.IAdaptable;
 import org.eclipse.ecf.core.identity.ID;
+import org.eclipse.equinox.security.storage.StorageException;
 
 /**
  * Storage interface for IContainer instances.
@@ -33,8 +34,9 @@ public interface IContainerStore extends IAdaptable {
 	 * 
 	 * @param containerAdapter the {@link IStorableContainerAdapter} to store.  Must not be <code>null</code>.
 	 * @return {@link IContainerEntry} result of storage.  Will not return <code>null</code>.
+	 * @throws StorageException if containerAdapter cannot be properly stored for whatever reason.
 	 */
-	public IContainerEntry store(IStorableContainerAdapter containerAdapter);
+	public IContainerEntry store(IStorableContainerAdapter containerAdapter) throws StorageException;
 
 	/**
 	 * Retrieve an IContainerEntry for a given container ID.
diff --git a/framework/bundles/org.eclipse.ecf.storage/src/org/eclipse/ecf/storage/IStorableContainerAdapter.java b/framework/bundles/org.eclipse.ecf.storage/src/org/eclipse/ecf/storage/IStorableContainerAdapter.java
index 3dedfba26..2dfbc4e4a 100644
--- a/framework/bundles/org.eclipse.ecf.storage/src/org/eclipse/ecf/storage/IStorableContainerAdapter.java
+++ b/framework/bundles/org.eclipse.ecf.storage/src/org/eclipse/ecf/storage/IStorableContainerAdapter.java
@@ -16,16 +16,40 @@ import org.eclipse.equinox.security.storage.ISecurePreferences;
 import org.eclipse.equinox.security.storage.StorageException;
 
 /**
- *
+ * Container adapter for storable containers.  Containers that can be stored via {@link IContainerStore}s
+ * must implement this interface.
  */
 public interface IStorableContainerAdapter extends IIdentifiable {
 
-	public boolean encrypt();
-
-	public String getFactoryName();
-
-	public void handleStore(ISecurePreferences prefs) throws StorageException;
-
-	public void handleRestore(ISecurePreferences prefs) throws StorageException;
+	/**
+	 * @return <code>true</code> if the implementer of this adapter should be stored as encrypted,
+	 * <code>false</code> if encryption should not be used.
+	 */
+	public boolean storeEncrypted();
+
+	/**
+	 * Get the container factory name for storage and restoration.  The returned
+	 * String will be used for creating a restored version of this container via {@link IContainerEntry#createContainer()}.
+	 * @return String that identifies the container factory name for this container.  The returned value must
+	 * not be <code>null</code>.
+	 */
+	public String getContainerFactoryName();
+
+	/**
+	 * Store the contents of the implementer in the given storage instance.  This method is called during {@link IContainerStore#store(IStorableContainerAdapter)}
+	 * and gives the implementer a chance to store any state.  The state is then passed to the {@link #restore(ISecurePreferences)}
+	 * method during restore of this container.
+	 * @param containerStorage the ISecurePreferences storage to use to store any state associated with this container.  
+	 * @throws StorageException if the store of this container should fail.
+	 */
+	public void store(ISecurePreferences containerStorage) throws StorageException;
+
+	/**
+	 * Restore the contents of the container given the storage instance.  This method is called during {@link IContainerEntry#createContainer()},
+	 * to give the implementer an opportunity to restore any state previously stored via {@link #store(ISecurePreferences)}.
+	 * @param containerStorage the ISecurePreferences storage whose contents were set via {@link #store(ISecurePreferences)}.
+	 * @throws StorageException if the restore should fail.
+	 */
+	public void restore(ISecurePreferences containerStorage) throws StorageException;
 
 }