Cleanup and documentation

scm-webapp/src/main/java/sonia/scm/api/rest/resources/AbstractManagerResource.java

@@ -37,8 +37,10 @@ package sonia.scm.api.rest.resources;
 
 import org.apache.commons.beanutils.BeanComparator;
 import org.apache.shiro.authz.AuthorizationException;
+
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
+
 import sonia.scm.LastModifiedAware;
 import sonia.scm.Manager;
 import sonia.scm.ModelObject;
@@ -48,13 +50,19 @@ import sonia.scm.util.AssertUtil;
 import sonia.scm.util.HttpUtil;
 import sonia.scm.util.Util;
 
-import javax.ws.rs.core.*;
-import javax.ws.rs.core.Response.Status;
+//~--- JDK imports ------------------------------------------------------------
+
 import java.util.Collection;
 import java.util.Comparator;
 import java.util.Date;
 
-//~--- JDK imports ------------------------------------------------------------
+import javax.ws.rs.core.CacheControl;
+import javax.ws.rs.core.EntityTag;
+import javax.ws.rs.core.GenericEntity;
+import javax.ws.rs.core.Request;
+import javax.ws.rs.core.Response;
+import javax.ws.rs.core.Response.Status;
+import javax.ws.rs.core.UriInfo;
 
 /**
  *
@@ -559,7 +567,7 @@ public abstract class AbstractManagerResource<T extends ModelObject,
    *
    * @return
    */
-  protected Collection<T> fetchItems(String sortby, boolean desc, int start,
+  private Collection<T> fetchItems(String sortby, boolean desc, int start,
     int limit)
   {
     AssertUtil.assertPositive(start);

scm-webapp/src/main/java/sonia/scm/api/rest/resources/GroupResource.java

@@ -41,17 +41,34 @@ import com.webcohesion.enunciate.metadata.rs.ResponseCode;
 import com.webcohesion.enunciate.metadata.rs.ResponseHeader;
 import com.webcohesion.enunciate.metadata.rs.StatusCodes;
 import com.webcohesion.enunciate.metadata.rs.TypeHint;
+
 import org.apache.shiro.SecurityUtils;
+
 import sonia.scm.group.Group;
 import sonia.scm.group.GroupException;
 import sonia.scm.group.GroupManager;
 import sonia.scm.security.Role;
 
-import javax.ws.rs.*;
-import javax.ws.rs.core.*;
+//~--- JDK imports ------------------------------------------------------------
+
 import java.util.Collection;
 
-//~--- JDK imports ------------------------------------------------------------
+import javax.ws.rs.Consumes;
+import javax.ws.rs.DELETE;
+import javax.ws.rs.DefaultValue;
+import javax.ws.rs.GET;
+import javax.ws.rs.POST;
+import javax.ws.rs.PUT;
+import javax.ws.rs.Path;
+import javax.ws.rs.PathParam;
+import javax.ws.rs.Produces;
+import javax.ws.rs.QueryParam;
+import javax.ws.rs.core.Context;
+import javax.ws.rs.core.GenericEntity;
+import javax.ws.rs.core.MediaType;
+import javax.ws.rs.core.Request;
+import javax.ws.rs.core.Response;
+import javax.ws.rs.core.UriInfo;
 
 /**
  * RESTful Web Service Resource to manage groups and their members.

scm-webapp/src/main/java/sonia/scm/api/rest/resources/RepositoryResource.java

@@ -42,26 +42,66 @@ import com.webcohesion.enunciate.metadata.rs.ResponseCode;
 import com.webcohesion.enunciate.metadata.rs.ResponseHeader;
 import com.webcohesion.enunciate.metadata.rs.StatusCodes;
 import com.webcohesion.enunciate.metadata.rs.TypeHint;
+
 import org.apache.shiro.SecurityUtils;
-import org.apache.shiro.authz.AuthorizationException;
+
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
+
 import sonia.scm.config.ScmConfiguration;
-import sonia.scm.repository.*;
-import sonia.scm.repository.api.*;
+import sonia.scm.repository.BlameResult;
+import sonia.scm.repository.Branches;
+import sonia.scm.repository.BrowserResult;
+import sonia.scm.repository.Changeset;
+import sonia.scm.repository.ChangesetPagingResult;
+import sonia.scm.repository.HealthChecker;
+import sonia.scm.repository.Permission;
+import sonia.scm.repository.Repository;
+import sonia.scm.repository.RepositoryException;
+import sonia.scm.repository.RepositoryIsNotArchivedException;
+import sonia.scm.repository.RepositoryManager;
+import sonia.scm.repository.RepositoryNotFoundException;
+import sonia.scm.repository.Tags;
+import sonia.scm.repository.api.BlameCommandBuilder;
+import sonia.scm.repository.api.BrowseCommandBuilder;
+import sonia.scm.repository.api.CatCommandBuilder;
+import sonia.scm.repository.api.CommandNotSupportedException;
+import sonia.scm.repository.api.DiffCommandBuilder;
+import sonia.scm.repository.api.DiffFormat;
+import sonia.scm.repository.api.LogCommandBuilder;
+import sonia.scm.repository.api.RepositoryService;
+import sonia.scm.repository.api.RepositoryServiceFactory;
 import sonia.scm.util.AssertUtil;
 import sonia.scm.util.HttpUtil;
 import sonia.scm.util.IOUtil;
 import sonia.scm.util.Util;
 
-import javax.ws.rs.*;
-import javax.ws.rs.core.*;
-import javax.ws.rs.core.Response.Status;
+//~--- JDK imports ------------------------------------------------------------
+
 import java.io.IOException;
+
 import java.util.ArrayList;
 import java.util.Collection;
 
-//~--- JDK imports ------------------------------------------------------------
+import javax.ws.rs.Consumes;
+import javax.ws.rs.DELETE;
+import javax.ws.rs.DefaultValue;
+import javax.ws.rs.GET;
+import javax.ws.rs.POST;
+import javax.ws.rs.PUT;
+import javax.ws.rs.Path;
+import javax.ws.rs.PathParam;
+import javax.ws.rs.Produces;
+import javax.ws.rs.QueryParam;
+import javax.ws.rs.core.Context;
+import javax.ws.rs.core.GenericEntity;
+import javax.ws.rs.core.MediaType;
+import javax.ws.rs.core.Request;
+import javax.ws.rs.core.Response;
+import javax.ws.rs.core.Response.Status;
+import javax.ws.rs.core.StreamingOutput;
+import javax.ws.rs.core.UriInfo;
+import org.apache.shiro.authz.AuthorizationException;
 
 /**
  * Repository related RESTful Web Service Endpoint.

scm-webapp/src/main/java/sonia/scm/api/rest/resources/UserResource.java

@@ -41,8 +41,10 @@ import com.webcohesion.enunciate.metadata.rs.ResponseCode;
 import com.webcohesion.enunciate.metadata.rs.ResponseHeader;
 import com.webcohesion.enunciate.metadata.rs.StatusCodes;
 import com.webcohesion.enunciate.metadata.rs.TypeHint;
+
 import org.apache.shiro.SecurityUtils;
 import org.apache.shiro.authc.credential.PasswordService;
+
 import sonia.scm.security.Role;
 import sonia.scm.user.User;
 import sonia.scm.user.UserException;
@@ -50,11 +52,26 @@ import sonia.scm.user.UserManager;
 import sonia.scm.util.AssertUtil;
 import sonia.scm.util.Util;
 
-import javax.ws.rs.*;
-import javax.ws.rs.core.*;
+//~--- JDK imports ------------------------------------------------------------
+
 import java.util.Collection;
 
-//~--- JDK imports ------------------------------------------------------------
+import javax.ws.rs.Consumes;
+import javax.ws.rs.DELETE;
+import javax.ws.rs.DefaultValue;
+import javax.ws.rs.GET;
+import javax.ws.rs.POST;
+import javax.ws.rs.PUT;
+import javax.ws.rs.Path;
+import javax.ws.rs.PathParam;
+import javax.ws.rs.Produces;
+import javax.ws.rs.QueryParam;
+import javax.ws.rs.core.Context;
+import javax.ws.rs.core.GenericEntity;
+import javax.ws.rs.core.MediaType;
+import javax.ws.rs.core.Request;
+import javax.ws.rs.core.Response;
+import javax.ws.rs.core.UriInfo;
 
 /**
  * RESTful Web Service Resource to manage users.

scm-webapp/src/main/java/sonia/scm/api/v2/FieldContainerResponseFilter.java

@@ -13,6 +13,13 @@ import javax.ws.rs.ext.Provider;
 import java.util.List;
 import java.util.Optional;
 
+/**
+ * <p>Post processor for rest requests filtering json responses when a {@value PARAMETER_FIELDS} query
+ * parameter is provided. In this case, only the given fields will returned. It is possible, to specify
+ * paths for nested fields. Multiple fields have to be devided using {@value FIELD_SEPARATOR}.</p>
+ * <p>This requires the {@link JsonMarshallingResponseFilter} to be processed first to create
+ * the {@link JsonNode} tree.</p>
+ */
 @Provider
 @Priority(Priorities.USER)
 public class FieldContainerResponseFilter implements ContainerResponseFilter {

scm-webapp/src/main/java/sonia/scm/api/v2/JsonMarshallingResponseFilter.java

@@ -15,6 +15,10 @@ import javax.ws.rs.container.ContainerResponseFilter;
 import javax.ws.rs.ext.Provider;
 import java.util.Set;
 
+/**
+ * Transforms json rest responses to {@link JsonNode} trees to support further post processing
+ * and processes all registered plugins for the {@link JsonEnricher} extension point.
+ */
 @Provider
 @Priority(Priorities.USER + 1000)
 public class JsonMarshallingResponseFilter implements ContainerResponseFilter {

scm-webapp/src/main/java/sonia/scm/api/v2/resources/ScmMediaType.java

@@ -1,4 +0,0 @@
-package sonia.scm.api.v2.resources;
-
-public class ScmMediaType {
-}

scm-webapp/src/main/java/sonia/scm/api/v2/resources/User2UserDtoMapper.java

@@ -5,6 +5,7 @@ import org.mapstruct.*;
 import sonia.scm.api.rest.resources.UserResource;
 import sonia.scm.user.User;
 import sonia.scm.user.UserPermissions;
+import sonia.scm.util.AssertUtil;
 
 import javax.ws.rs.core.UriInfo;
 import java.time.Instant;
@@ -43,7 +44,7 @@ public abstract class User2UserDtoMapper {
 
   @Mapping(target = "creationDate")
   Instant mapTime(Long epochMilli) {
-    // TODO assert parameter not null
+    AssertUtil.assertIsNotNull(epochMilli);
     return Instant.ofEpochMilli(epochMilli);
   }
 

scm-webapp/src/main/java/sonia/scm/api/v2/resources/UserCollection2DtoMapper.java

@@ -29,7 +29,7 @@ public class UserCollection2DtoMapper {
     this.userToDtoMapper = userToDtoMapper;
   }
 
-  public UserCollectionDto userCollectionToUserDto(UriInfo uriInfo, int pageNumber, int pageSize, PageResult<User> pageResult) {
+  public UserCollectionDto userCollectionToDto(UriInfo uriInfo, int pageNumber, int pageSize, PageResult<User> pageResult) {
     NumberedPaging paging = zeroBasedNumberedPaging(pageNumber, pageSize, pageResult.hasMore());
     List<UserDto> dtos = pageResult.getEntities().stream().map(user -> userToDtoMapper.userToUserDto(user, uriInfo)).collect(Collectors.toList());
 

scm-webapp/src/main/java/sonia/scm/api/v2/resources/UserCollectionResource.java

@@ -12,12 +12,21 @@ import sonia.scm.user.UserException;
 import sonia.scm.user.UserManager;
 import sonia.scm.web.VndMediaType;
 
-import javax.ws.rs.*;
-import javax.ws.rs.core.*;
+import javax.ws.rs.DefaultValue;
+import javax.ws.rs.GET;
+import javax.ws.rs.POST;
+import javax.ws.rs.Path;
+import javax.ws.rs.Produces;
+import javax.ws.rs.QueryParam;
+import javax.ws.rs.core.Context;
+import javax.ws.rs.core.GenericEntity;
+import javax.ws.rs.core.Request;
+import javax.ws.rs.core.Response;
+import javax.ws.rs.core.UriInfo;
 import java.io.IOException;
 import java.util.Collection;
 
-@Produces(VndMediaType.USER)
+@Produces(VndMediaType.USER_COLLECTION)
 public class UserCollectionResource extends AbstractManagerResource<User, UserException> {
   public static final int DEFAULT_PAGE_SIZE = 10;
   private final UserDto2UserMapper dtoToUserMapper;
@@ -57,9 +66,14 @@ public class UserCollectionResource extends AbstractManagerResource<User, UserEx
     @QueryParam("desc") boolean desc) {
     PageResult<User> pageResult = fetchPage(sortby, desc, page, pageSize);
 
-    return Response.ok(new UserCollection2DtoMapper(userToDtoMapper).userCollectionToUserDto(uriInfo, page, pageSize, pageResult)).build();
+    return Response.ok(new UserCollection2DtoMapper(userToDtoMapper).userCollectionToDto(uriInfo, page, pageSize, pageResult)).build();
   }
 
+  /**
+   * Creates a new user.
+   * @param userDto The user to be created.
+   * @return A response with the link to the new user (if created successfully).
+   */
   @POST
   @Path("")
   @StatusCodes({

scm-webapp/src/main/java/sonia/scm/api/v2/resources/UserSubResource.java

@@ -12,8 +12,17 @@ import sonia.scm.user.UserException;
 import sonia.scm.user.UserManager;
 import sonia.scm.web.VndMediaType;
 
-import javax.ws.rs.*;
-import javax.ws.rs.core.*;
+import javax.ws.rs.DELETE;
+import javax.ws.rs.GET;
+import javax.ws.rs.PUT;
+import javax.ws.rs.Path;
+import javax.ws.rs.PathParam;
+import javax.ws.rs.Produces;
+import javax.ws.rs.core.Context;
+import javax.ws.rs.core.GenericEntity;
+import javax.ws.rs.core.Request;
+import javax.ws.rs.core.Response;
+import javax.ws.rs.core.UriInfo;
 import java.util.Collection;