bug4813: added javadocs

java/com.sap.sailing.domain.common/src/com/sap/sailing/domain/common/security/DomainIdentifierStrategy.java

@@ -7,6 +7,11 @@ import com.sap.sse.security.shared.impl.WildcardPermissionEncoder;
 
 public interface DomainIdentifierStrategy extends IdentifierStrategy {
 
+    /**
+     * Identifier strategy that is used for tracked races. A tracked race
+     * is identified by a {@link RegattaAndRaceIdentifier} that has to be used
+     * for building a permission.
+     */
     static IdentifierStrategy TRACKED_RACE = new IdentifierStrategy() {
 
         @Override
@@ -18,6 +23,9 @@ public interface DomainIdentifierStrategy extends IdentifierStrategy {
 
     };
 
+    /**
+     * Identifier strategy that is used for {@link MediaTrack}s.
+     */
     static IdentifierStrategy MEDIA_TRACK = new IdentifierStrategy() {
 
         @Override

java/com.sap.sse.security.common/src/com/sap/sse/security/shared/HasPermissions.java

@@ -59,31 +59,64 @@ public interface HasPermissions {
      *            can be any string; this method will take care of encoding the identifiers such that they are legal in
      *            the context of a permission part; see also {@link PermissionStringEncoder}
      */
-    /*String getStringPermission(Action action);*/
     @Deprecated
     String getStringPermissionForTypeRelativeIdentifiers(Action action, String... typeRelativeObjectIdentifier);
+    
+    /**
+     * Produces a string permission for this permission, the <code>mode</code> specified as the second wildcard
+     * permission segment, and the <code>objectIdentifier</code> as the third wildcard permission segment. The object
+     * identifiers must be unique within the scope defined by this {@link HasPermissions} which represents an object
+     * category or type, such as, e.g., "LEADERBOARD."
+     * 
+     * @param object
+     *            can be any object that can be passed to the identifer strategy to determine the type relative
+     *            identifier for this object. What type of object can be passed is defined by the identifer strategy
+     */
     String getStringPermissionForObject(Action action, Object object);
 
     /**
-     * Qualifies the {@code objectIdentifier} which only has to be unique within the scope of the type identified
-     * by this permission with this permission's type name. For example, if this permission is for the "LEADERBOARD"
-     * type, and the {@code objectIdentifier} is {@code "abc"} then the resulting qualified identifier will be
+     * Qualifies the {@code objectIdentifier} which only has to be unique within the scope of the type identified by
+     * this permission with this permission's type name. For example, if this permission is for the "LEADERBOARD" type,
+     * and the {@code objectIdentifier} is {@code "abc"} then the resulting qualified identifier will be
      * "LEADERBOARD/abc". This assumes that the {@link #name()} method returns only values that do not contain a "/".
      */
     @Deprecated
     QualifiedObjectIdentifier getQualifiedObjectIdentifierByString(String typeRelativeObjectIdentifier);
+    
+    /**
+     * Qualifies the {@code objectIdentifier} which only has to be unique within the scope of the type identified by
+     * this permission with this permission's type name. For example, if this permission is for the "LEADERBOARD" type,
+     * and the {@code objectIdentifier} is {@code "abc"} then the resulting qualified identifier will be
+     * "LEADERBOARD/abc". This assumes that the {@link #name()} method returns only values that do not contain a "/".
+     * 
+     * @param object
+     *            can be any object that can be passed to the identifer strategy to determine the type relative
+     *            identifier for this object. What type of object can be passed is defined by the identifer strategy
+     */
     <T> QualifiedObjectIdentifier getQualifiedObjectIdentifier(T object);
 
     /**
      * Same as {@link #getStringPermissionForTypeRelativeIdentifiers(Action, String...)}, only that the result is a
      * {@link WildcardPermission} instead of a {@link String}
-     * @deprecated  better option is to use the variant {@link #getPermissionForObject(Action action, Object object)} instead.
-     * {@link #getPermissionForObject(Action action, Object object)} uses this implementation in a private manner but is
-     * creating the permission id by using the corresponding {{@link #identifierStrategy()}.
-     * If no concrete object (e.g. unit test) is available, this method can still be used.
+     * 
+     * @deprecated better option is to use the variant {@link #getPermissionForObject(Action action, Object object)}
+     *             instead. {@link #getPermissionForObject(Action action, Object object)} uses this implementation in a
+     *             private manner but is creating the permission id by using the corresponding
+     *             {{@link #identifierStrategy()}. If no concrete object (e.g. unit test) is available, this method can
+     *             still be used.
      */
     @Deprecated
     WildcardPermission getPermissionForObjects(Action action, String... objectIdentifiers);
+
+    /**
+     * Same as {@link #getStringPermissionForTypeRelativeIdentifiers(Action, String...)}, only that the result is a
+     * {@link WildcardPermission} instead of a {@link String}
+     * 
+     * @param object
+     *            can be any object that can be passed to the identifer strategy to determine the type relative
+     *            identifier for this object. What type of object can be passed is defined by the identifer strategy
+     * 
+     */
     WildcardPermission getPermissionForObject(Action action, Object object);
 
     /**

java/com.sap.sse.security.common/src/com/sap/sse/security/shared/IdentifierStrategy.java

@@ -8,6 +8,10 @@ public interface IdentifierStrategy {
 
     <T> String getIdentifierAsString(T object);
 
+    /**
+     * Identifier strategy that is used for object types that implement the
+     * interface {@link Named}.
+     */
     static IdentifierStrategy NAMED = new IdentifierStrategy() {
 
         @Override
@@ -18,6 +22,10 @@ public interface IdentifierStrategy {
 
     };
 
+    /**
+     * Identifier strategy that can be used for object types that implement the
+     * interface {@link WithID}.
+     */
     static IdentifierStrategy ID = new IdentifierStrategy() {
 
         @Override
@@ -28,6 +36,10 @@ public interface IdentifierStrategy {
 
     };
 
+    /**
+     * Identifier strategy that can be used for object types are represented
+     * by a {@link String} object.
+     */
     static IdentifierStrategy STRING = new IdentifierStrategy() {
 
         @Override
@@ -37,8 +49,14 @@ public interface IdentifierStrategy {
 
     };
 
+    /**
+     * Identifier strategy that can be used for object types are represented
+     * by a {@link String} object. This is used to specify the concrete case
+     * of a server that is identified by a servename.
+     */
     static IdentifierStrategy SERVERNAME = STRING;
 
+    @Deprecated
     static IdentifierStrategy TO_SPECIFY = new IdentifierStrategy() {
 
         @Override
@@ -48,6 +66,11 @@ public interface IdentifierStrategy {
 
     };
 
+    /**
+     * Used to mark a permission that does not require a conceret object
+     * permission. If used to build a permission, it will throw a
+     * {@link UnsupportedOperationException}.
+     */
     static IdentifierStrategy NO_OP = new IdentifierStrategy() {
 
         @Override