Added comments.
Change-Id: I1fb300d27579b44b016a1ea2a4437619aab66200
diff --git a/full/src/main/java/de/ids_mannheim/korap/service/AnnotationService.java b/full/src/main/java/de/ids_mannheim/korap/service/AnnotationService.java
index 4952091..83e4d9e 100644
--- a/full/src/main/java/de/ids_mannheim/korap/service/AnnotationService.java
+++ b/full/src/main/java/de/ids_mannheim/korap/service/AnnotationService.java
@@ -16,7 +16,13 @@
import de.ids_mannheim.korap.exceptions.KustvaktException;
import de.ids_mannheim.korap.exceptions.StatusCodes;
import de.ids_mannheim.korap.web.CoreResponseHandler;
+import de.ids_mannheim.korap.web.controller.AnnotationController;
+/** AnnotationService defines the logic behind {@link AnnotationController}.
+ *
+ * @author margaretha
+ *
+ */
@Service
public class AnnotationService {
diff --git a/full/src/main/java/de/ids_mannheim/korap/service/ResourceService.java b/full/src/main/java/de/ids_mannheim/korap/service/ResourceService.java
index 937f337..b079e9c 100644
--- a/full/src/main/java/de/ids_mannheim/korap/service/ResourceService.java
+++ b/full/src/main/java/de/ids_mannheim/korap/service/ResourceService.java
@@ -11,7 +11,13 @@
import de.ids_mannheim.korap.dto.ResourceDto;
import de.ids_mannheim.korap.dto.converter.ResourceConverter;
import de.ids_mannheim.korap.entity.Resource;
+import de.ids_mannheim.korap.web.controller.ResourceController;
+/** ResourceService defines the logic behind {@link ResourceController}.
+ *
+ * @author margaretha
+ *
+ */
@Service
public class ResourceService {
diff --git a/full/src/main/java/de/ids_mannheim/korap/service/UserGroupService.java b/full/src/main/java/de/ids_mannheim/korap/service/UserGroupService.java
index f704668..5ff4ef9 100644
--- a/full/src/main/java/de/ids_mannheim/korap/service/UserGroupService.java
+++ b/full/src/main/java/de/ids_mannheim/korap/service/UserGroupService.java
@@ -18,8 +18,16 @@
import de.ids_mannheim.korap.entity.UserGroup;
import de.ids_mannheim.korap.entity.UserGroupMember;
import de.ids_mannheim.korap.exceptions.KustvaktException;
+import de.ids_mannheim.korap.web.controller.UserGroupController;
import de.ids_mannheim.korap.web.input.UserGroupJson;
+/** UserGroupService defines the logic behind user group web controller.
+ *
+ * @see UserGroupController
+ *
+ * @author margaretha
+ *
+ */
@Service
public class UserGroupService {
@@ -33,11 +41,14 @@
private UserGroupConverter converter;
- /** Only USER_GROUP_ADMINs are allowed to see the members of the group.
+ /** Only users with {@link PredefinedRole#USER_GROUP_ADMIN}
+ * are allowed to see the members of the group.
*
* @param username username
* @return a list of usergroups
* @throws KustvaktException
+ *
+ * @see {@link PredefinedRole}
*/
public List<UserGroupDto> retrieveUserGroup (String username)
throws KustvaktException {
@@ -70,13 +81,16 @@
/** Group owner is automatically added when creating a group.
* Do not include owners in group members.
*
- * USER_GROUP_MEMBER and VC_ACCESS_MEMBER roles are automatically
- * assigned to each group member.
+ * {@link PredefinedRole#USER_GROUP_MEMBER} and
+ * {@link PredefinedRole#VC_ACCESS_MEMBER} roles are
+ * automatically assigned to each group member.
*
- * USER_GROUP_MEMBER cannot see other group members and may remove
- * himself from the group.
+ * {@link PredefinedRole#USER_GROUP_MEMBER} restrict users
+ * to see other group members and allow users to remove
+ * themselves from the groups.
*
- * VC_ACCESS_MEMBER can only read group VC.
+ * {@link PredefinedRole#VC_ACCESS_MEMBER} allow user to
+ * read group VC.
*
* @see /full/src/main/resources/db/predefined/V3.2__insert_predefined_roles.sql
*
@@ -115,12 +129,26 @@
}
}
+ /** Updates the {@link GroupMemberStatus} of a pending member
+ * to {@link GroupMemberStatus#ACTIVE}.
+ *
+ * @param groupId groupId
+ * @param username the username of the group member
+ * @throws KustvaktException
+ */
public void subscribe (int groupId, String username)
throws KustvaktException {
groupMemberDao.approveMember(username, groupId);
}
+ /** Updates the {@link GroupMemberStatus} of a member to
+ * {@link GroupMemberStatus#DELETED}
+ *
+ * @param groupId groupId
+ * @param username member's username
+ * @throws KustvaktException
+ */
public void unsubscribe (int groupId, String username)
throws KustvaktException {
groupMemberDao.deleteMember(username, groupId, true);
diff --git a/full/src/main/java/de/ids_mannheim/korap/web/controller/AnnotationController.java b/full/src/main/java/de/ids_mannheim/korap/web/controller/AnnotationController.java
index 939b13c..8af6516 100644
--- a/full/src/main/java/de/ids_mannheim/korap/web/controller/AnnotationController.java
+++ b/full/src/main/java/de/ids_mannheim/korap/web/controller/AnnotationController.java
@@ -24,7 +24,6 @@
import de.ids_mannheim.korap.service.AnnotationService;
import de.ids_mannheim.korap.utils.JsonUtils;
import de.ids_mannheim.korap.web.CoreResponseHandler;
-import de.ids_mannheim.korap.web.filter.AuthenticationFilter;
import de.ids_mannheim.korap.web.filter.DemoUserFilter;
import de.ids_mannheim.korap.web.filter.PiwikFilter;
diff --git a/full/src/main/java/de/ids_mannheim/korap/web/controller/UserController.java b/full/src/main/java/de/ids_mannheim/korap/web/controller/UserController.java
index 2bee6a4..a0b2923 100644
--- a/full/src/main/java/de/ids_mannheim/korap/web/controller/UserController.java
+++ b/full/src/main/java/de/ids_mannheim/korap/web/controller/UserController.java
@@ -58,7 +58,9 @@
import de.ids_mannheim.korap.web.filter.DemoUserFilter;
import de.ids_mannheim.korap.web.filter.PiwikFilter;
-/**
+/** Some of the APIs are not applicable due to changes in DB,
+ * i.e. users are not saved in the DB.
+ *
* @author hanl, margaretha
* @lastUpdate 11/2017
*/
@@ -70,7 +72,7 @@
@Autowired
private FullResponseHandler kustvaktResponseHandler;
-
+
private static Logger jlog = LoggerFactory.getLogger(UserController.class);
@Autowired
private AuthenticationManagerIface controller;
@@ -81,7 +83,8 @@
// fixme: json contains password in clear text. Encrypt request?
// EM: no encryption is needed for communications over https.
// It should not be necessary in IDS internal network.
-
+
+ @Deprecated
// fixme: should also collect service exception, not just db exception!
@POST
@Path("register")
@@ -127,12 +130,13 @@
jlog.error("Failed creating confirmation and expiry tokens.");
// EM: why illegal argument when uri fragment/param is self-generated
throw kustvaktResponseHandler.throwit(StatusCodes.ILLEGAL_ARGUMENT,
- "failed to validate uri parameter", "confirmation fragment");
+ "failed to validate uri parameter",
+ "confirmation fragment");
}
}
-
+ @Deprecated
//todo: password update in special function? --> password reset only!
@POST
@Path("update")
@@ -158,7 +162,7 @@
return Response.ok().build();
}
-
+ @Deprecated
@GET
@Path("confirm")
@Produces(MediaType.TEXT_HTML)
@@ -181,7 +185,7 @@
return Response.ok().build();
}
-
+ @Deprecated
// todo: auditing!
@POST
@Path("requestReset")
@@ -237,7 +241,7 @@
}
}
-
+ @Deprecated
@POST
@Path("reset")
@Produces(MediaType.TEXT_HTML)
@@ -272,8 +276,7 @@
Userdata data = controller.getUserData(user, UserDetails.class);
Set<String> base_scope = StringUtils.toSet(scopes, " ");
- if (scopes != null)
- base_scope.retainAll(StringUtils.toSet(scopes));
+ if (scopes != null) base_scope.retainAll(StringUtils.toSet(scopes));
scopes = StringUtils.toString(base_scope);
m = Scopes.mapScopes(scopes, data);
return Response.ok(m.toEntity()).build();
@@ -315,8 +318,7 @@
@Context Locale locale, Map settings) {
TokenContext ctx = (TokenContext) context.getUserPrincipal();
- if (settings == null)
- return Response.notModified().build();
+ if (settings == null) return Response.notModified().build();
try {
User user = controller.getUser(ctx.getUsername());
@@ -378,8 +380,7 @@
@Context Locale locale, Map details) {
TokenContext ctx = (TokenContext) context.getUserPrincipal();
- if (details == null)
- return Response.notModified().build();
+ if (details == null) return Response.notModified().build();
try {
User user = controller.getUser(ctx.getUsername());
@@ -418,8 +419,8 @@
Iterator<JsonNode> node = nodes.elements();
while (node.hasNext()) {
JsonNode cursor = node.next();
- UserQuery query = new UserQuery(cursor.path("id").asInt(),
- user.getId());
+ UserQuery query =
+ new UserQuery(cursor.path("id").asInt(), user.getId());
query.setQueryLanguage(cursor.path("queryLanguage").asText());
query.setQuery(cursor.path("query").asText());
query.setDescription(cursor.path("description").asText());
@@ -461,7 +462,7 @@
}
}
-
+ @Deprecated
@DELETE
@ResourceFilters({ AuthenticationFilter.class, PiwikFilter.class,
BlockingFilter.class })
diff --git a/full/src/main/java/de/ids_mannheim/korap/web/controller/UserGroupController.java b/full/src/main/java/de/ids_mannheim/korap/web/controller/UserGroupController.java
index e625414..5b4fb6c 100644
--- a/full/src/main/java/de/ids_mannheim/korap/web/controller/UserGroupController.java
+++ b/full/src/main/java/de/ids_mannheim/korap/web/controller/UserGroupController.java
@@ -31,6 +31,16 @@
import de.ids_mannheim.korap.web.filter.PiwikFilter;
import de.ids_mannheim.korap.web.input.UserGroupJson;
+/** UserGroupController defines web APIs related to user groups,
+ * such as creating a user group, listing groups of a user,
+ * adding members to a group and subscribing (confirming an
+ * invitation) to a group.
+ *
+ * These APIs are only available to logged-in users.
+ *
+ * @author margaretha
+ *
+ */
@Controller
@Path("group")
@Produces(MediaType.APPLICATION_JSON + ";charset=utf-8")
diff --git a/full/src/main/java/de/ids_mannheim/korap/web/controller/VirtualCorpusController.java b/full/src/main/java/de/ids_mannheim/korap/web/controller/VirtualCorpusController.java
index 5f193c6..cfef7fb 100644
--- a/full/src/main/java/de/ids_mannheim/korap/web/controller/VirtualCorpusController.java
+++ b/full/src/main/java/de/ids_mannheim/korap/web/controller/VirtualCorpusController.java
@@ -32,6 +32,14 @@
import de.ids_mannheim.korap.web.filter.PiwikFilter;
import de.ids_mannheim.korap.web.input.VirtualCorpusJson;
+/** VirtualCorpusController defines web APIs related to virtual corpus
+ * such as creating, deleting and listing user virtual corpora.
+ *
+ * These APIs are only available to logged-in users.
+ *
+ * @author margaretha
+ *
+ */
@Controller
@Path("vc")
@Produces(MediaType.APPLICATION_JSON + ";charset=utf-8")
@@ -70,7 +78,7 @@
// EM: nicer URL with username?
@GET
@Path("user")
- public Response getUserVC (@Context SecurityContext securityContext){
+ public Response getUserVC (@Context SecurityContext securityContext) {
String result;
TokenContext context =
(TokenContext) securityContext.getUserPrincipal();
diff --git a/full/src/main/resources/log4j.properties b/full/src/main/resources/log4j.properties
index b975c78..352062e 100644
--- a/full/src/main/resources/log4j.properties
+++ b/full/src/main/resources/log4j.properties
@@ -36,4 +36,4 @@
log4j.logger.de.ids_mannheim.korap.security.ac = ERROR, policyLog
-log4j.logger.de.ids_mannheim.korap.authentication = debug, authLog
\ No newline at end of file
+log4j.logger.de.ids_mannheim.korap.authentication = ERROR, authLog
\ No newline at end of file