From b7f933d1d73ec51737538d904ba5ab40f58e39a4 Mon Sep 17 00:00:00 2001 From: Sebastian Sdorra Date: Tue, 5 Jul 2011 21:19:38 +0200 Subject: [PATCH] added javadoc for the sonia.scm.group package --- .../sonia/scm/group/AbstractGroupManager.java | 24 +-- .../src/main/java/sonia/scm/group/Group.java | 138 +++++++++--------- .../scm/group/GroupAllreadyExistExeption.java | 2 + .../java/sonia/scm/group/GroupException.java | 17 ++- .../java/sonia/scm/group/GroupListener.java | 9 +- .../java/sonia/scm/group/GroupManager.java | 9 +- .../java/sonia/scm/group/package-info.java | 37 +++++ 7 files changed, 142 insertions(+), 94 deletions(-) create mode 100644 scm-core/src/main/java/sonia/scm/group/package-info.java diff --git a/scm-core/src/main/java/sonia/scm/group/AbstractGroupManager.java b/scm-core/src/main/java/sonia/scm/group/AbstractGroupManager.java index 8982271d7c..cc6dc3166d 100644 --- a/scm-core/src/main/java/sonia/scm/group/AbstractGroupManager.java +++ b/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 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 listenerSet = new HashSet(); } diff --git a/scm-core/src/main/java/sonia/scm/group/Group.java b/scm-core/src/main/java/sonia/scm/group/Group.java index 89496051c4..81d4850599 100644 --- a/scm-core/src/main/java/sonia/scm/group/Group.java +++ b/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 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 } /** - * 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 members) { @@ -101,13 +102,13 @@ public class Group implements ModelObject, Iterable } /** - * 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 //~--- 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 } /** - * Method description + * Remove all members of the group. * */ public void clear() @@ -146,10 +147,10 @@ public class Group implements ModelObject, Iterable } /** - * 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 } /** - * 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 } /** - * 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 } /** - * 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 } /** - * 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 iterator() @@ -296,12 +297,12 @@ public class Group implements ModelObject, Iterable } /** - * 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 } /** - * 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 //~--- 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 } /** - * 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 } /** - * 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 } /** - * 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 } /** - * 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 getMembers() { @@ -404,10 +406,10 @@ public class Group implements ModelObject, Iterable } /** - * 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 } /** - * 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 } /** - * 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 } /** - * 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 //~--- 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 } /** - * 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 } /** - * 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 } /** - * Method description + * Sets the members of the group. * * - * @param members + * @param members of the group */ public void setMembers(List members) { @@ -498,10 +500,10 @@ public class Group implements ModelObject, Iterable } /** - * 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 } /** - * 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 //~--- 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 members; - /** Field description */ + /** name of this group */ private String name; - /** Field description */ + /** type of this group */ private String type; } diff --git a/scm-core/src/main/java/sonia/scm/group/GroupAllreadyExistExeption.java b/scm-core/src/main/java/sonia/scm/group/GroupAllreadyExistExeption.java index 04ba93a41a..09ae7a16c8 100644 --- a/scm-core/src/main/java/sonia/scm/group/GroupAllreadyExistExeption.java +++ b/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 */ diff --git a/scm-core/src/main/java/sonia/scm/group/GroupException.java b/scm-core/src/main/java/sonia/scm/group/GroupException.java index 331a5256e5..e0dc799e92 100644 --- a/scm-core/src/main/java/sonia/scm/group/GroupException.java +++ b/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) { diff --git a/scm-core/src/main/java/sonia/scm/group/GroupListener.java b/scm-core/src/main/java/sonia/scm/group/GroupListener.java index d09ac6fc21..ea1f94f387 100644 --- a/scm-core/src/main/java/sonia/scm/group/GroupListener.java +++ b/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); } diff --git a/scm-core/src/main/java/sonia/scm/group/GroupManager.java b/scm-core/src/main/java/sonia/scm/group/GroupManager.java index 36aeb5969b..2917c047be 100644 --- a/scm-core/src/main/java/sonia/scm/group/GroupManager.java +++ b/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 getGroupsForMember(String member); } diff --git a/scm-core/src/main/java/sonia/scm/group/package-info.java b/scm-core/src/main/java/sonia/scm/group/package-info.java new file mode 100644 index 0000000000..35032304ff --- /dev/null +++ b/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;