added javadoc for the sonia.scm.group package

scm-core/src/main/java/sonia/scm/group/AbstractGroupManager.java

@@ -44,6 +44,8 @@ import java.util.HashSet;
 import java.util.Set;
 
 /**
+ * Abstract base class for {@link GroupManager} implementations. This class
+ * implements the listener methods of the {@link GroupManager} interface.
  *
  * @author Sebastian Sdorra
  */
@@ -51,10 +53,10 @@ public abstract class AbstractGroupManager implements GroupManager
 {
 
   /**
-   *   Method description
+   * Register a {@link GroupListener}.
    *
    *
-   *   @param listener
+   * @param listener - {@link GroupListener} to register
    */
   @Override
   public void addListener(GroupListener listener)
@@ -63,10 +65,10 @@ public abstract class AbstractGroupManager implements GroupManager
   }
 
   /**
-   * Method description
+   * Register a {@link java.util.Collection} of {@link GroupListener}s.
    *
    *
-   * @param listeners
+   * @param listeners - listeners to register
    */
   @Override
   public void addListeners(Collection<GroupListener> listeners)
@@ -75,10 +77,10 @@ public abstract class AbstractGroupManager implements GroupManager
   }
 
   /**
-   * Method description
+   * Remove specified {@link GroupListener}.
    *
    *
-   * @param listener
+   * @param listener to remove
    */
   @Override
   public void removeListener(GroupListener listener)
@@ -87,11 +89,11 @@ public abstract class AbstractGroupManager implements GroupManager
   }
 
   /**
-   * Method description
+   * Calls the {@link GroupListener#onEvent(Group,sonia.scm.HandlerEvent)}
+   * method of all registered listeners.
    *
-   *
-   * @param group
-   * @param event
+   * @param group that has changed
+   * @param event type of change event
    */
   protected void fireEvent(Group group, HandlerEvent event)
   {
@@ -103,6 +105,6 @@ public abstract class AbstractGroupManager implements GroupManager
 
   //~--- fields ---------------------------------------------------------------
 
-  /** Field description */
+  /** registered listeners */
   private Set<GroupListener> listenerSet = new HashSet<GroupListener>();
 }

scm-core/src/main/java/sonia/scm/group/Group.java

@@ -50,6 +50,7 @@ import javax.xml.bind.annotation.XmlAccessorType;
 import javax.xml.bind.annotation.XmlRootElement;
 
 /**
+ * Organizes users into a group for easier permissions management.
  *
  * @author Sebastian Sdorra
  */
@@ -70,12 +71,12 @@ public class Group implements ModelObject, Iterable<String>
   public Group() {}
 
   /**
-   * Constructs ...
+   * Constructs {@link Group} object.
    *
    *
    *
-   * @param type
-   * @param name
+   * @param type of the group
+   * @param name of the group
    */
   public Group(String type, String name)
   {
@@ -85,13 +86,13 @@ public class Group implements ModelObject, Iterable<String>
   }
 
   /**
-   * Constructs ...
+   * Constructs {@link Group} object.
    *
    *
    *
-   * @param type
-   * @param name
-   * @param members
+   * @param type of the group
+   * @param name of the group
+   * @param members of the groups
    */
   public Group(String type, String name, List<String> members)
   {
@@ -101,13 +102,13 @@ public class Group implements ModelObject, Iterable<String>
   }
 
   /**
-   * Constructs ...
+   * Constructs {@link Group} object.
    *
    *
    *
-   * @param type
-   * @param name
-   * @param members
+   * @param type of the group
+   * @param name of the group
+   * @param members of the groups
    */
   public Group(String type, String name, String... members)
   {
@@ -124,12 +125,12 @@ public class Group implements ModelObject, Iterable<String>
   //~--- methods --------------------------------------------------------------
 
   /**
-   * Method description
+   * Add a new member to the group.
    *
    *
-   * @param member
+   * @param member - The name of new group member
    *
-   * @return
+   * @return true if the operation was successful
    */
   public boolean add(String member)
   {
@@ -137,7 +138,7 @@ public class Group implements ModelObject, Iterable<String>
   }
 
   /**
-   * Method description
+   * Remove all members of the group.
    *
    */
   public void clear()
@@ -146,10 +147,10 @@ public class Group implements ModelObject, Iterable<String>
   }
 
   /**
-   * Method description
+   * Returns a clone of the group.
    *
    *
-   * @return
+   * @return a clone of the group
    *
    */
   @Override
@@ -170,10 +171,10 @@ public class Group implements ModelObject, Iterable<String>
   }
 
   /**
-   * Method description
+   * Copies all properties of this group to the given one.
    *
    *
-   * @param group
+   * @param group to copies all properties of this one
    */
   public void copyProperties(Group group)
   {
@@ -184,12 +185,12 @@ public class Group implements ModelObject, Iterable<String>
   }
 
   /**
-   * Method description
+   * Returns true if this {@link Group} is the same as the obj argument.
    *
    *
-   * @param obj
+   * @param obj - the reference object with which to compare
    *
-   * @return
+   * @return true if this {@link Group} is the same as the obj argument
    */
   @Override
   public boolean equals(Object obj)
@@ -251,10 +252,10 @@ public class Group implements ModelObject, Iterable<String>
   }
 
   /**
-   * Method description
+   * Returns a hash code value for this {@link Group}.
    *
    *
-   * @return
+   * @return a hash code value for this {@link Group}
    */
   @Override
   public int hashCode()
@@ -284,10 +285,10 @@ public class Group implements ModelObject, Iterable<String>
   }
 
   /**
-   * Method description
+   * Returns a {@link java.util.Iterator} for the members of this {@link Group}.
    *
    *
-   * @return
+   * @return a {@link java.util.Iterator} for the members of this {@link Group}
    */
   @Override
   public Iterator<String> iterator()
@@ -296,12 +297,12 @@ public class Group implements ModelObject, Iterable<String>
   }
 
   /**
-   * Method description
+   * Remove the given member from this group.
    *
    *
-   * @param member
+   * @param member to remove from this group
    *
-   * @return
+   * @return true if the operation was successful
    */
   public boolean remove(String member)
   {
@@ -309,10 +310,10 @@ public class Group implements ModelObject, Iterable<String>
   }
 
   /**
-   * Method description
+   * Returns a {@link String} that represents this group.
    *
    *
-   * @return
+   * @return a {@link String} that represents this group
    */
   @Override
   public String toString()
@@ -342,10 +343,10 @@ public class Group implements ModelObject, Iterable<String>
   //~--- get methods ----------------------------------------------------------
 
   /**
-   * Method description
+   * Returns a timestamp of the creation date of this group.
    *
    *
-   * @return
+   * @return a timestamp of the creation date of this group
    */
   public Long getCreationDate()
   {
@@ -353,10 +354,10 @@ public class Group implements ModelObject, Iterable<String>
   }
 
   /**
-   * Method description
+   * Returns the description of this group.
    *
    *
-   * @return
+   * @return  the description of this group
    */
   public String getDescription()
   {
@@ -364,10 +365,11 @@ public class Group implements ModelObject, Iterable<String>
   }
 
   /**
-   * Method description
+   * Returns the unique name of this group. This method is an alias for the
+   * {@link #getName()} method.
    *
    *
-   * @return
+   * @return the unique name of this group
    */
   @Override
   public String getId()
@@ -376,10 +378,10 @@ public class Group implements ModelObject, Iterable<String>
   }
 
   /**
-   * Method description
+   * Returns a timestamp of the last modified date of this group.
    *
    *
-   * @return
+   * @return a timestamp of the last modified date of this group
    */
   @Override
   public Long getLastModified()
@@ -388,10 +390,10 @@ public class Group implements ModelObject, Iterable<String>
   }
 
   /**
-   * Method description
+   * Returns a {@link java.util.List} of all members of this group.
    *
    *
-   * @return
+   * @return a {@link java.util.List} of all members of this group
    */
   public List<String> getMembers()
   {
@@ -404,10 +406,10 @@ public class Group implements ModelObject, Iterable<String>
   }
 
   /**
-   * Method description
+   * Returns the unique name of this group.
    *
    *
-   * @return
+   * @return the unique name of this group
    */
   public String getName()
   {
@@ -415,10 +417,10 @@ public class Group implements ModelObject, Iterable<String>
   }
 
   /**
-   * Method description
+   * Returns the type of this group. The default type is xml.
    *
    *
-   * @return
+   * @return the type of this group
    */
   @Override
   public String getType()
@@ -427,12 +429,12 @@ public class Group implements ModelObject, Iterable<String>
   }
 
   /**
-   * Method description
+   * Returns true if the member is a member of this group.
    *
    *
-   * @param member
+   * @param member - The name of the member
    *
-   * @return
+   * @return true if the member is a member of this group
    */
   public boolean isMember(String member)
   {
@@ -440,10 +442,10 @@ public class Group implements ModelObject, Iterable<String>
   }
 
   /**
-   * Method description
+   * Returns true if the group is valid.
    *
    *
-   * @return
+   * @return true if the group is valid
    */
   @Override
   public boolean isValid()
@@ -454,10 +456,10 @@ public class Group implements ModelObject, Iterable<String>
   //~--- set methods ----------------------------------------------------------
 
   /**
-   * Method description
+   * Sets the date the group was created.
    *
    *
-   * @param creationDate
+   * @param creationDate - date the group was last modified
    */
   public void setCreationDate(Long creationDate)
   {
@@ -465,10 +467,10 @@ public class Group implements ModelObject, Iterable<String>
   }
 
   /**
-   * Method description
+   * Sets the description of the group.
    *
    *
-   * @param description
+   * @param description of the group
    */
   public void setDescription(String description)
   {
@@ -476,10 +478,10 @@ public class Group implements ModelObject, Iterable<String>
   }
 
   /**
-   * Method description
+   * Sets the date the group was last modified.
    *
    *
-   * @param lastModified
+   * @param lastModified - date the group was last modified
    */
   public void setLastModified(Long lastModified)
   {
@@ -487,10 +489,10 @@ public class Group implements ModelObject, Iterable<String>
   }
 
   /**
-   * Method description
+   * Sets the members of the group.
    *
    *
-   * @param members
+   * @param members of the group
    */
   public void setMembers(List<String> members)
   {
@@ -498,10 +500,10 @@ public class Group implements ModelObject, Iterable<String>
   }
 
   /**
-   * Method description
+   * Sets the name of the group.
    *
    *
-   * @param name
+   * @param name of the group
    */
   public void setName(String name)
   {
@@ -509,10 +511,10 @@ public class Group implements ModelObject, Iterable<String>
   }
 
   /**
-   * Method description
+   * Sets the type of the group.
    *
    *
-   * @param type
+   * @param type of the group
    */
   public void setType(String type)
   {
@@ -521,21 +523,21 @@ public class Group implements ModelObject, Iterable<String>
 
   //~--- fields ---------------------------------------------------------------
 
-  /** Field description */
+  /** timestamp of the creation date of this group */
   private Long creationDate;
 
-  /** Field description */
+  /** description of this group */
   private String description;
 
-  /** Field description */
+  /** timestamp of the last modified date of this group */
   private Long lastModified;
 
-  /** Field description */
+  /** members of this group */
   private List<String> members;
 
-  /** Field description */
+  /** name of this group */
   private String name;
 
-  /** Field description */
+  /** type of this group */
   private String type;
 }

scm-core/src/main/java/sonia/scm/group/GroupAllreadyExistExeption.java

@@ -34,6 +34,8 @@
 package sonia.scm.group;
 
 /**
+ * This {@link Exception} is thrown when trying to create a group 
+ * that already exists.
  *
  * @author Sebastian Sdorra
  */

scm-core/src/main/java/sonia/scm/group/GroupException.java

@@ -34,6 +34,7 @@
 package sonia.scm.group;
 
 /**
+ * General {@link Exception} for group errors.
  *
  * @author Sebastian Sdorra
  */
@@ -46,7 +47,7 @@ public class GroupException extends Exception
   //~--- constructors ---------------------------------------------------------
 
   /**
-   * Constructs ...
+   * Constructs a {@link GroupException} object.
    *
    */
   public GroupException()
@@ -55,10 +56,10 @@ public class GroupException extends Exception
   }
 
   /**
-   * Constructs ...
+   * Constructs a {@link GroupException} object.
    *
    *
-   * @param message
+   * @param message for the exception
    */
   public GroupException(String message)
   {
@@ -66,10 +67,10 @@ public class GroupException extends Exception
   }
 
   /**
-   * Constructs ...
+   * Constructs a {@link GroupException} object.
    *
    *
-   * @param cause
+   * @param cause of the exception
    */
   public GroupException(Throwable cause)
   {
@@ -77,11 +78,11 @@ public class GroupException extends Exception
   }
 
   /**
-   * Constructs ...
+   * Constructs a {@link GroupException} object.
    *
    *
-   * @param message
-   * @param cause
+   * @param message of the exception
+   * @param cause of the exception
    */
   public GroupException(String message, Throwable cause)
   {

scm-core/src/main/java/sonia/scm/group/GroupListener.java

@@ -39,6 +39,9 @@ import sonia.scm.HandlerEvent;
 import sonia.scm.plugin.ExtensionPoint;
 
 /**
+ * Listener for group events. {@link GroupListener} can be registered with
+ * {@link sonia.scm.plugin.ext.Extension} annotation or with the 
+ * {@link GroupManager#addListener(java.lang.Object)}.
  *
  * @author Sebastian Sdorra
  */
@@ -47,11 +50,11 @@ public interface GroupListener
 {
 
   /**
-   * Method description
+   * Called when a group change event is fired.
    *
    *
-   * @param group
-   * @param event
+   * @param group that has changed
+   * @param event type of change event
    */
   public void onEvent(Group group, HandlerEvent event);
 }

scm-core/src/main/java/sonia/scm/group/GroupManager.java

@@ -44,7 +44,8 @@ import sonia.scm.search.Searchable;
 import java.util.Collection;
 
 /**
- *
+ * The central class for managing {@link Group}s.
+ * This class is a singleton and is available via injection.
  * @author Sebastian Sdorra
  */
 public interface GroupManager
@@ -53,12 +54,12 @@ public interface GroupManager
 {
 
   /**
-   * Method description
+   * Returns a {@link Collection} of all groups assigned to the given member.
    *
    *
-   * @param member
+   * @param member - The name of the member
    *
-   * @return
+   * @return all groups assigned to the given member
    */
   public Collection<Group> getGroupsForMember(String member);
 }

scm-core/src/main/java/sonia/scm/group/package-info.java

@@ -0,0 +1,37 @@
+/**
+ * Copyright (c) 2010, Sebastian Sdorra
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ * 3. Neither the name of SCM-Manager; nor the names of its
+ *    contributors may be used to endorse or promote products derived from this
+ *    software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY
+ * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * http://bitbucket.org/sdorra/scm-manager
+ *
+ */
+
+
+
+/**
+ * Package for the SCM-Manager group API.
+ */
+package sonia.scm.group;