From 082554e2ce77bb3ec933942533ba7d64cc1c2aa3 Mon Sep 17 00:00:00 2001 From: Thomas Wiese Date: Mon, 10 Dec 2018 11:00:34 +0100 Subject: [PATCH] bug4813: added javadocs --- .../security/DomainIdentifierStrategy.java | 8 +++ .../sse/security/shared/HasPermissions.java | 49 ++++++++++++++++--- .../security/shared/IdentifierStrategy.java | 23 +++++++++ 3 files changed, 72 insertions(+), 8 deletions(-) diff --git a/java/com.sap.sailing.domain.common/src/com/sap/sailing/domain/common/security/DomainIdentifierStrategy.java b/java/com.sap.sailing.domain.common/src/com/sap/sailing/domain/common/security/DomainIdentifierStrategy.java index 0adeddaa2a9..9df0058c447 100644 --- a/java/com.sap.sailing.domain.common/src/com/sap/sailing/domain/common/security/DomainIdentifierStrategy.java +++ b/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 diff --git a/java/com.sap.sse.security.common/src/com/sap/sse/security/shared/HasPermissions.java b/java/com.sap.sse.security.common/src/com/sap/sse/security/shared/HasPermissions.java index c0808aa5317..2b51f869f5a 100644 --- a/java/com.sap.sse.security.common/src/com/sap/sse/security/shared/HasPermissions.java +++ b/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 mode specified as the second wildcard + * permission segment, and the objectIdentifier 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 + */ 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); /** diff --git a/java/com.sap.sse.security.common/src/com/sap/sse/security/shared/IdentifierStrategy.java b/java/com.sap.sse.security.common/src/com/sap/sse/security/shared/IdentifierStrategy.java index 7c550621c1c..4bf91eb3168 100644 --- a/java/com.sap.sse.security.common/src/com/sap/sse/security/shared/IdentifierStrategy.java +++ b/java/com.sap.sse.security.common/src/com/sap/sse/security/shared/IdentifierStrategy.java @@ -8,6 +8,10 @@ public interface IdentifierStrategy { 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