Update Javadocs

8 files changed, 119 insertions, 26 deletions

diff --git a/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/spi/transfer/FileSystemTransferSystem.java b/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/spi/transfer/FileSystemTransferSystem.java
index da62a32625..6658a154c8 100644
--- a/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/spi/transfer/FileSystemTransferSystem.java
+++ b/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/spi/transfer/FileSystemTransferSystem.java
@@ -33,6 +33,8 @@ import java.io.OutputStream;
 import java.io.Writer;
 
 /**
+ * A {@link CDOTransferSystem transfer system} that abstracts the external file system.
+ *
  * @author Eike Stepper
  * @since 4.2
  */
diff --git a/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/spi/transfer/ResourceFactoryRegistryWithoutDefaults.java b/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/spi/transfer/ResourceFactoryRegistryWithoutDefaults.java
index 75dd22131b..5c92cb485c 100644
--- a/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/spi/transfer/ResourceFactoryRegistryWithoutDefaults.java
+++ b/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/spi/transfer/ResourceFactoryRegistryWithoutDefaults.java
@@ -4,30 +4,36 @@
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
- * 
+ *
  * Contributors:
  *    Eike Stepper - initial API and implementation
  */
 package org.eclipse.emf.cdo.spi.transfer;
 
+import org.eclipse.emf.cdo.transfer.CDOTransferElement;
+
 import org.eclipse.emf.common.util.URI;
 import org.eclipse.emf.ecore.resource.Resource;
 import org.eclipse.emf.ecore.resource.Resource.Factory;
+import org.eclipse.emf.ecore.resource.Resource.Factory.Registry;
 import org.eclipse.emf.ecore.resource.impl.ResourceFactoryRegistryImpl;
 
 /**
+ * A {@link Registry resource factory registry} that does <b>not</b> delegate and does <b>not</b> recognize default extensions or default content types.
+ * This registry can be used to determine whether a {@link CDOTransferElement transfer element} can be loaded as an EMF model {@link Resource resource} or not.
+ *
  * @author Eike Stepper
  */
 public class ResourceFactoryRegistryWithoutDefaults extends ResourceFactoryRegistryImpl
 {
   public ResourceFactoryRegistryWithoutDefaults()
   {
-    getProtocolToFactoryMap().putAll(Resource.Factory.Registry.INSTANCE.getProtocolToFactoryMap());
-    getExtensionToFactoryMap().putAll(Resource.Factory.Registry.INSTANCE.getExtensionToFactoryMap());
-    getContentTypeToFactoryMap().putAll(Resource.Factory.Registry.INSTANCE.getContentTypeToFactoryMap());
+    getProtocolToFactoryMap().putAll(Registry.INSTANCE.getProtocolToFactoryMap());
+    getExtensionToFactoryMap().putAll(Registry.INSTANCE.getExtensionToFactoryMap());
+    getContentTypeToFactoryMap().putAll(Registry.INSTANCE.getContentTypeToFactoryMap());
 
-    getExtensionToFactoryMap().remove(Resource.Factory.Registry.DEFAULT_EXTENSION);
-    getContentTypeToFactoryMap().remove(Resource.Factory.Registry.DEFAULT_CONTENT_TYPE_IDENTIFIER);
+    getExtensionToFactoryMap().remove(Registry.DEFAULT_EXTENSION);
+    getContentTypeToFactoryMap().remove(Registry.DEFAULT_CONTENT_TYPE_IDENTIFIER);
   }
 
   @Override
@@ -35,4 +41,4 @@ public class ResourceFactoryRegistryWithoutDefaults extends ResourceFactoryRegis
   {
     return null;
   }
-}
\ No newline at end of file
+}
diff --git a/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/spi/transfer/package-info.java b/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/spi/transfer/package-info.java
new file mode 100644
index 0000000000..5ea636888b
--- /dev/null
+++ b/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/spi/transfer/package-info.java
@@ -0,0 +1,17 @@
+/*
+ * Copyright (c) 2004 - 2012 Eike Stepper (Berlin, Germany) and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ *    Eike Stepper - initial API and implementation
+ */
+
+/**
+ * Service provider concepts for dealing with transfers of {@link org.eclipse.emf.cdo.eresource.CDOResourceLeaf resources}
+ * between {@link org.eclipse.emf.cdo.transfer.CDOTransferSystem systems}.
+ */
+package org.eclipse.emf.cdo.spi.transfer;
+
diff --git a/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/transfer/CDOTransfer.java b/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/transfer/CDOTransfer.java
index a65dd5f68b..5c0d1d6ce3 100644
--- a/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/transfer/CDOTransfer.java
+++ b/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/transfer/CDOTransfer.java
@@ -13,10 +13,12 @@ package org.eclipse.emf.cdo.transfer;
 import org.eclipse.emf.cdo.spi.transfer.ResourceFactoryRegistryWithoutDefaults;
 
 import org.eclipse.net4j.util.event.Event;
+import org.eclipse.net4j.util.event.IEvent;
 import org.eclipse.net4j.util.event.IListener;
 import org.eclipse.net4j.util.event.INotifier;
 import org.eclipse.net4j.util.event.Notifier;
 import org.eclipse.net4j.util.io.IOUtil;
+import org.eclipse.net4j.util.lifecycle.ILifecycleEvent;
 
 import org.eclipse.emf.common.notify.Notification;
 import org.eclipse.emf.common.notify.impl.AdapterImpl;
@@ -44,6 +46,19 @@ import java.util.Map;
 import java.util.Set;
 
 /**
+ * Abstracts the transfer of a tree of {@link CDOTransferElement elements} for a
+ * {@link #getSourceSystem() source} to a {@link #getTargetSystem() target} {@link CDOTransferSystem system}.
+ * <p>
+ * The mappings of the source elements to their target elements is represented as a tree of {@link CDOTransferMapping transfer mappings}.
+ * <p>
+ * A transfer fires the following {@link IEvent events}:
+ * <ul>
+ * <li>{@link ChildrenChangedEvent} when the {@link CDOTransferMapping#getChildren() children} of a mapping have changed.
+ * <li>{@link RelativePathChangedEvent} when the {@link CDOTransferMapping#getRelativePath() relative path} of a mapping has changed.
+ * <li>{@link TransferTypeChangedEvent} when the {@link CDOTransferMapping#getTransferType() transfer type} of a mapping has changed.
+ * <li>{@link UnmappedModelsEvent} when the set of {@link CDOTransfer.ModelTransferContext#getUnmappedModels() unmapped models} has changed.
+ * </ul>
+ *
  * @author Eike Stepper
  * @since 4.2
  */
@@ -402,7 +417,10 @@ public class CDOTransfer implements INotifier
   }
 
   /**
+   * An abstract base implementation of a {@link CDOTransferMapping mapping} {@link ILifecycleEvent event}.
+   *
    * @author Eike Stepper
+   * @noextend This class is not intended to be subclassed by clients.
    */
   public static abstract class MappingEvent extends Event
   {
@@ -425,7 +443,11 @@ public class CDOTransfer implements INotifier
   }
 
   /**
+   * A {@link MappingEvent mapping event} fired from a {@link CDOTransfer transfer} when
+   * the {@link CDOTransferMapping#getChildren() children} of a mapping have changed.
+   *
    * @author Eike Stepper
+   * @noextend This class is not intended to be subclassed by clients.
    */
   public static class ChildrenChangedEvent extends MappingEvent
   {
@@ -459,6 +481,8 @@ public class CDOTransfer implements INotifier
     }
 
     /**
+     * Enumerates the possible values of {@link ChildrenChangedEvent#getKind()}.
+     *
      * @author Eike Stepper
      */
     public enum Kind
@@ -468,7 +492,11 @@ public class CDOTransfer implements INotifier
   }
 
   /**
+   * A {@link MappingEvent mapping event} fired from a {@link CDOTransfer transfer} when
+   * the {@link CDOTransferMapping#getRelativePath() relative path} of a mapping has changed.
+   *
    * @author Eike Stepper
+   * @noextend This class is not intended to be subclassed by clients.
    */
   public static class RelativePathChangedEvent extends MappingEvent
   {
@@ -503,7 +531,11 @@ public class CDOTransfer implements INotifier
   }
 
   /**
+   * A {@link MappingEvent mapping event} fired from a {@link CDOTransfer transfer} when
+   * the {@link CDOTransferMapping#getTransferType() transfer type} of a mapping has changed.
+   *
    * @author Eike Stepper
+   * @noextend This class is not intended to be subclassed by clients.
    */
   public static class TransferTypeChangedEvent extends MappingEvent
   {
@@ -538,7 +570,11 @@ public class CDOTransfer implements INotifier
   }
 
   /**
+   * An {@link IEvent event} fired from a {@link CDOTransfer transfer} when
+   * the set of {@link CDOTransfer.ModelTransferContext#getUnmappedModels() unmapped models} has changed.
+   *
    * @author Eike Stepper
+   * @noextend This class is not intended to be subclassed by clients.
    */
   public static class UnmappedModelsEvent extends Event
   {
@@ -551,6 +587,8 @@ public class CDOTransfer implements INotifier
   }
 
   /**
+   * Encapsulates the model-specific aspects of a {@link CDOTransfer transfer}.
+   *
    * @author Eike Stepper
    */
   public static class ModelTransferContext
@@ -651,22 +689,11 @@ public class CDOTransfer implements INotifier
       map.put(contentType, factory);
     }
 
-    public Set<Resource> resolve()
+    public Set<Resource> getUnmappedModels()
     {
       if (unmappedModels == null)
       {
-        Set<Resource> mappedModels = resourceElements.keySet();
-
-        ResourceSet resourceSet = getSourceResourceSet();
-        EList<Resource> resources = resourceSet.getResources();
-
-        // if (resources.addAll(mappedModels))
-        // {
-        // EcoreUtil.resolveAll(resourceSet);
-        // }
-
-        unmappedModels = new HashSet<Resource>(resources);
-        unmappedModels.removeAll(mappedModels);
+        unmappedModels = resolve();
         fireUnmappedModelsEvent();
       }
 
@@ -689,6 +716,18 @@ public class CDOTransfer implements INotifier
       return old;
     }
 
+    protected Set<Resource> resolve()
+    {
+      Set<Resource> mappedModels = resourceElements.keySet();
+
+      ResourceSet resourceSet = getSourceResourceSet();
+      EList<Resource> resources = resourceSet.getResources();
+
+      Set<Resource> unmappedModels = new HashSet<Resource>(resources);
+      unmappedModels.removeAll(mappedModels);
+      return unmappedModels;
+    }
+
     protected void fireUnmappedModelsEvent()
     {
       transfer.notifier.fireEvent(new UnmappedModelsEvent(transfer));
@@ -795,6 +834,8 @@ public class CDOTransfer implements INotifier
     }
 
     /**
+     * An {@link AdapterImpl adapter} for a {@link ResourceSet resource set} that resolves all proxies in all resources when they are loaded.
+     *
      * @author Eike Stepper
      */
     public static class ResolveProxyAdapter extends AdapterImpl
@@ -880,6 +921,8 @@ public class CDOTransfer implements INotifier
       }
 
       /**
+       * An {@link AdapterImpl adapter} for a {@link Resource resource} that resolves all proxies in that resource when it's demand loaded.
+       *
        * @author Eike Stepper
        */
       public static class LoadResourceAdapter extends AdapterImpl
@@ -910,10 +953,13 @@ public class CDOTransfer implements INotifier
   }
 
   /**
+   * Reserved for future use.
+   *
    * @author Eike Stepper
+   * @noextend This class is not intended to be subclassed by clients.
+   * @noimplement This interface is not intended to be implemented by clients.
    */
   public interface ModelTransferResolution
   {
-
   }
 }
diff --git a/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/transfer/CDOTransferElement.java b/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/transfer/CDOTransferElement.java
index adb5cebcec..672c947902 100644
--- a/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/transfer/CDOTransferElement.java
+++ b/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/transfer/CDOTransferElement.java
@@ -20,6 +20,8 @@ import org.eclipse.core.runtime.Path;
 import java.io.InputStream;
 
 /**
+ * An abstraction of the elements (such as files or folders) of a {@link CDOTransferSystem transfer system}.
+ *
  * @author Eike Stepper
  * @since 4.2
  */
diff --git a/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/transfer/CDOTransferMapping.java b/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/transfer/CDOTransferMapping.java
index 72a1f912bb..20d49199c7 100644
--- a/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/transfer/CDOTransferMapping.java
+++ b/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/transfer/CDOTransferMapping.java
@@ -13,6 +13,8 @@ package org.eclipse.emf.cdo.transfer;
 import org.eclipse.core.runtime.IPath;
 
 /**
+ * The mapping of a source {@link CDOTransferElement element} to a target element in the context of a specific {@link CDOTransfer transfer}.
+ *
  * @author Eike Stepper
  * @since 4.2
  */
@@ -61,16 +63,21 @@ public interface CDOTransferMapping extends Comparable<CDOTransferMapping>
   public CDOTransferElement getTarget();
 
   /**
-     * @author Eike Stepper
-     */
+   * Enumerates the possibles values of {@link CDOTransferMapping#getStatus()}.
+   *
+   * @author Eike Stepper
+   */
   public enum Status
   {
     NEW, MERGE, CONFLICT
   }
 
   /**
-     * @author Eike Stepper
-     */
+   * A call-back that is called for a {@link CDOTransferMapping mapping} and all its {@link CDOTransferMapping#getChildren() children} when
+   * passed into its {@link CDOTransferMapping#accept(Visitor) accept()} method.
+   *
+   * @author Eike Stepper
+   */
   public interface Visitor
   {
     public boolean visit(CDOTransferMapping mapping);
diff --git a/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/transfer/CDOTransferSystem.java b/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/transfer/CDOTransferSystem.java
index ad20c2cfcf..6d65c18c6b 100644
--- a/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/transfer/CDOTransferSystem.java
+++ b/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/transfer/CDOTransferSystem.java
@@ -26,6 +26,12 @@ import java.io.IOException;
 import java.io.InputStream;
 
 /**
+ * An abstraction of an end point system of a {@link CDOTransfer transfer}.
+ * <p>
+ * It's used for example in {@link CDOTransfer#getSourceSystem()} and {@link CDOTransfer#getTargetSystem()}.
+ * The arguments of the map() methods in {@link CDOTransfer} are treated as {@link IPath paths} relative to the source transfer system.
+ * The {@link CDOTransferMapping#getTarget() targets} of the created mappings are determined by paths relative to the target transfer system.
+ *
  * @author Eike Stepper
  * @since 4.2
  */
diff --git a/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/transfer/CDOTransferType.java b/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/transfer/CDOTransferType.java
index 2c538bf2ee..cb60442669 100644
--- a/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/transfer/CDOTransferType.java
+++ b/plugins/org.eclipse.emf.cdo.transfer/src/org/eclipse/emf/cdo/transfer/CDOTransferType.java
@@ -20,8 +20,11 @@ import java.util.HashMap;
 import java.util.Map;
 
 /**
+ * Specifies how to treat a source {@link CDOTransferElement element} when it is mapped to a target element by a {@link CDOTransferMapping transfer mapping}.
+ *
  * @author Eike Stepper
  * @since 4.2
+ * @noextend This class is not intended to be subclassed by clients.
  */
 public class CDOTransferType implements Comparable<CDOTransferType>
 {
@@ -132,9 +135,13 @@ public class CDOTransferType implements Comparable<CDOTransferType>
   }
 
   /**
+   * A {@link CDOTransferType transfer type} for text {@link CDOTransferElement elements} that have a special {@link #getEncoding() encoding}.
+   * <p>
+   * Call {@link CDOTransferType#text(String)} to get an encoding-specific instance.
+   *
    * @author Eike Stepper
    */
-  public static class Text extends CDOTransferType
+  public static final class Text extends CDOTransferType
   {
     private String encoding;