grooming, bugfixing, and some javadoc

photoalbum-common/src/main/java/com/mgu/photoalbum/exception/PhotoalbumException.java

@@ -1,5 +1,11 @@
 package com.mgu.photoalbum.exception;
 
+/**
+ * This is the base exception type for all exceptions within the photoalbum service. It provides the
+ * means to retain the cause (if there is any) as well as an error message and an error code.
+ *
+ * @author Markus Günther ([email protected])
+ */
 abstract public class PhotoalbumException extends RuntimeException {
 
  private static final long serialVersionUID = -8563374709814927511L;

photoalbum-fileio-adapter/src/main/java/com/mgu/photoalbum/adapter/fileio/InputStreamAdapter.java

@@ -6,6 +6,11 @@
 import java.io.InputStream;
 import java.util.Base64;
 
+/**
+ * Provides some convenience methods to handle {@link InputStream}.
+ *
+ * @author Markus Günther ([email protected])
+ */
 public class InputStreamAdapter {
 
  public InputStream getBase64DecodingInputStream(final String base64EncodedData) {

photoalbum-fileio-adapter/src/main/java/com/mgu/photoalbum/adapter/fileio/PathAdapter.java

@@ -14,10 +14,27 @@
 import java.nio.file.Path;
 import java.nio.file.StandardCopyOption;
 
+/**
+ * Provides the means to handle basic I/O using {@link Path}.
+ *
+ * @author Markus Günther ([email protected])
+ */
 public class PathAdapter {
 
  private static final Logger LOGGER = LoggerFactory.getLogger(PathAdapter.class);
 
+ /**
+ * Reads the contents of the file located at {@code Path} and returns them as
+ * byte array.
+ *
+ * @param path
+ * refers to a location on the filesystem
+ * @throws UnableToReadFromFilesystemException
+ * in case the read operation fails
+ * @return
+ * {@code byte[]} array containing all the bytes that were read from
+ * the file located at the given {@code Path}
+ */
  public byte[] readBytes(final Path path) {
  try {
  return convertToBytes(Files.newInputStream(path));
@@ -26,19 +43,6 @@ public byte[] readBytes(final Path path) {
  }
  }
 
- /**
- * Reads in all bytes from the given {@link InputStream} and returns them as
- * byte array.
- *
- * @param in
- * Represents the {@link InputStream} from which to read
- * @throws IOException
- * In case reading from the given {@link InputStream} raises an
- * {@link IOException}
- * @return
- * <code>byte[]</code> array containing all the bytes that were
- * read from the given {@link InputStream}
- */
  private byte[] convertToBytes(final InputStream in) throws IOException {
  try {
  return IOUtils.toByteArray(in);
@@ -50,6 +54,17 @@ private byte[] convertToBytes(final InputStream in) throws IOException {
  }
  }
 
+ /**
+ * Reads the contents of the file located at {@code Path} as String (binary-safe).
+ *
+ * @param path
+ * refers to a location on the filesystem
+ * @throws UnableToReadFromFilesystemException
+ * in case the read operation fails
+ * @return
+ * the contents of the file located at the given {@code Path} in form
+ * of a binary-safe {@link String}
+ */
  public String readString(final Path path) {
  try {
  return convertToString(Files.newInputStream(path));

photoalbum-fileio-adapter/src/main/java/com/mgu/photoalbum/adapter/fileio/UnableToCopyFileException.java

@@ -2,6 +2,13 @@
 
 import com.mgu.photoalbum.exception.PhotoalbumException;
 
+/**
+ * This exception is raised whenever a copy operation to the filesystem (from any I/O resource) or to a
+ * different location on the filesystem fails. Causes for this are manifold. Thus, the root cause is retained
+ * with this exception.
+ *
+ * @author Markus Günther ([email protected])
+ */
 public class UnableToCopyFileException extends PhotoalbumException {
 
  private static final String ERROR_MESSAGE_ONLY_DESTINATION = "Unable to write data to %s.";

photoalbum-fileio-adapter/src/main/java/com/mgu/photoalbum/adapter/fileio/UnableToDecodeFromBase64Exception.java

@@ -2,6 +2,12 @@
 
 import com.mgu.photoalbum.exception.PhotoalbumException;
 
+/**
+ * This exception is raised when a Base64-decoding wrapper on an {@code InputStream} is unable
+ * to decode the stream data properly.
+ *
+ * @author Markus Günther ([email protected])
+ */
 public class UnableToDecodeFromBase64Exception extends PhotoalbumException {
 
  private static final String ERROR_MESSAGE = "Unable to decode given Base64-encoded data.";

photoalbum-fileio-adapter/src/main/java/com/mgu/photoalbum/adapter/fileio/UnableToReadFromFilesystemException.java

@@ -2,6 +2,13 @@
 
 import com.mgu.photoalbum.exception.PhotoalbumException;
 
+/**
+ * This exception is raised if the service was unable to read a requested file from
+ * the filesystem. The cause for this is is potentially manifold, so the root cause
+ * is retained within this exception.
+ *
+ * @author Markus Günther ([email protected])
+ */
 public class UnableToReadFromFilesystemException extends PhotoalbumException {
 
  private static final String ERROR_MESSAGE = "Unable to read the contents of %s.";

photoalbum-fileio-adapter/src/main/java/com/mgu/photoalbum/adapter/fileio/UnableToWriteToFilesystemException.java

@@ -2,6 +2,13 @@
 
 import com.mgu.photoalbum.exception.PhotoalbumException;
 
+/**
+ * This exception is raised if the service was unable to write a given file
+ * to the filesystem. The cause for this is potentially manifold, so the root
+ * cause is retained with this exception.
+ *
+ * @author Markus Günther ([email protected])
+ */
 public class UnableToWriteToFilesystemException extends PhotoalbumException {
 
  private static final String ERROR_MESSAGE = "Unable to write to filesystem (path was %s).";

photoalbum-management/src/main/java/com/mgu/photoalbum/domain/Album.java

@@ -10,6 +10,15 @@
 import org.joda.time.DateTime;
 import org.joda.time.DateTimeZone;
 
+/**
+ * A {@code Album} is a managed resource that has been created by user (referred to as owner) and
+ * contains {@link Photo}s. This association is inversely implemented within the system: Photos know
+ * to which albums they belong to.
+ *
+ * Only owners are granted the right to access their albums and perform modifications on it.
+ *
+ * @author Markus Günther ([email protected])
+ */
 public class Album extends Document {
 
  public static final String DOCUMENT_TYPE = "album";

photoalbum-management/src/main/java/com/mgu/photoalbum/domain/Photo.java

@@ -15,6 +15,19 @@
 import java.util.List;
 import java.util.stream.Collectors;
 
+/**
+ * A {@code Photo} is a managed resource that has been created by a user (referred to
+ * as the owner) and belongs to an existing {@link Album}. Its lifetime is bound to the
+ * lifetime of the {@link Album} it belongs to. As such, if the corresponding {@link Album}
+ * is deleted, all its containing photos are as well.
+ *
+ * A {@code Photo} can be tagged.
+ *
+ * Only owners are granted the right to access their photo and perform modifications
+ * on it.
+ *
+ * @author Markus Günther ([email protected])
+ */
 public class Photo extends Document {
 
  public static final String DOCUMENT_TYPE = "photo";

photoalbum-management/src/main/java/com/mgu/photoalbum/service/AlbumCommandService.java

@@ -1,8 +1,34 @@
 package com.mgu.photoalbum.service;
 
+/**
+ * {@code AlbumCommandService} provides the means to create and delete domain objects of type {@code Album}.
+ * This service does not determine if a command is authorized. Clients of this class must ensure that the
+ * requested command is admissible.
+ *
+ * @author Markus Günther ([email protected])
+ */
 public interface AlbumCommandService {
 
+ /**
+ * Creates a new album with the provided metadata.
+ *
+ * @param ownerId
+ * represents the ID of the user that requested to create the album
+ * @param title
+ * represents the title of the album
+ * @return
+ * unique ID that is identifies the newly created album
+ */
  String createAlbum(String ownerId, String title);
 
- void deleteAlbum(String id);
+ /**
+ * Deletes the album identified by the given {@code albumId}. Implementing classes must ensure
+ * that this method also deletes all photos that are associated with the album. Implementing
+ * classes may handle a non-existing album as good case, since the system already has reached
+ * a convergent stace with regard to a missing album (this should not raise an error).
+ *
+ * @param albumId
+ * Uniquely identifies an album
+ */
+ void deleteAlbum(String albumId);
 }

photoalbum-management/src/main/java/com/mgu/photoalbum/service/AlbumDoesNotExistException.java

@@ -2,6 +2,11 @@
 
 import com.mgu.photoalbum.exception.PhotoalbumException;
 
+/**
+ * The requested album does not exist.
+ *
+ * @author Markus Günther ([email protected])
+ */
 public class AlbumDoesNotExistException extends PhotoalbumException {
 
  private static final String ERROR_MESSAGE = "An album for the given album ID %s does not exist.";

photoalbum-management/src/main/java/com/mgu/photoalbum/service/AlbumQueryService.java

@@ -4,9 +4,34 @@
 
 import java.util.List;
 
+/**
+ * {@code AlbumQueryService} provides the means to lookup {@link Album}s by their ID or search for them.
+ *
+ * @author Markus Günther ([email protected])
+ */
 public interface AlbumQueryService {
 
- Album albumById(final String id);
+ /**
+ * Retrieves the {@link Album} identified by the given ID.
+ *
+ * @param albumId
+ * Uniquely identifies an {@link Album} within the system
+ * @throws AlbumDoesNotExistException
+ * in case the ID refers to a non-existing album
+ * @return
+ * {@link Album} identified by the given ID
+ */
+ Album albumById(final String albumId);
 
+ /**
+ * Performs a search request using the provided search parameters encoded with
+ * {@link AlbumSearchRequest}.
+ *
+ * @param searchRequest
+ * data holder which is used to parameterize the search for albums
+ * @return
+ * Instance of {@link AlbumSearchResult} which holds the search results
+ * and retains the search parameters that led to those results
+ */
  AlbumSearchResult search(final AlbumSearchRequest searchRequest);
 }

photoalbum-management/src/main/java/com/mgu/photoalbum/service/AlbumSearchRequest.java

@@ -2,6 +2,11 @@
 
 import org.apache.commons.lang3.StringUtils;
 
+/**
+ * Container for Album-related search parameters.
+ *
+ * @author Markus Günther ([email protected])
+ */
 public class AlbumSearchRequest {
 
  public static class AlbumSearchRequestBuilder {

photoalbum-management/src/main/java/com/mgu/photoalbum/service/AlbumSearchResult.java

@@ -5,11 +5,14 @@
 
 public class AlbumSearchResult {
 
+ private final AlbumSearchRequest searchRequest;
+
  private final int total;
 
  private final List<AlbumHit> hits;
 
- public AlbumSearchResult(final int total, final List<AlbumHit> hits) {
+ public AlbumSearchResult(final AlbumSearchRequest searchRequest, final int total, final List<AlbumHit> hits) {
+ this.searchRequest = searchRequest;
  this.total = total;
  this.hits = hits;
  }
@@ -25,4 +28,8 @@ public int getHitCount() {
  public List<AlbumHit> getHits() {
  return Collections.unmodifiableList(hits);
  }
+
+ public AlbumSearchRequest getSearchRequest() {
+ return this.searchRequest;
+ }
 }

photoalbum-management/src/main/java/com/mgu/photoalbum/service/AlbumService.java

@@ -64,6 +64,7 @@ public void deleteAlbum(final String albumId) {
  // deleting an existing album and trying to delete a non-existing album leads to the
  // same state convergence. thus, we do not treat a deletion request to a non-existing album
  // not as an error, but return immediately
+ LOGGER.debug("Received a delete command for a non-existing album (ID " + albumId + ").");
  return;
  }
  final Album album = repository.get(albumId);
@@ -73,11 +74,11 @@ public void deleteAlbum(final String albumId) {
  }
 
  @Override
- public Album albumById(final String id) {
- if (!repository.contains(id)) {
- throw new AlbumDoesNotExistException(id);
+ public Album albumById(final String albumId) {
+ if (!repository.contains(albumId)) {
+ throw new AlbumDoesNotExistException(albumId);
  }
- final Album album = repository.get(id);
+ final Album album = repository.get(albumId);
  return album;
  }
 
@@ -88,7 +89,7 @@ public AlbumSearchResult search(final AlbumSearchRequest searchRequest) {
  .stream()
  .map(album -> new AlbumHit(album, numberOfPhotosInAlbum(album.getId()), randomThumbnailId(album.getId())))
  .collect(Collectors.toList());
- return new AlbumSearchResult(hits.size(), hits);
+ return new AlbumSearchResult(searchRequest, hits.size(), hits);
  }
 
  private int numberOfPhotosInAlbum(final String albumId) {

photoalbum-management/src/main/java/com/mgu/photoalbum/service/ImageDoesNotExistException.java

@@ -2,6 +2,11 @@
 
 import com.mgu.photoalbum.exception.PhotoalbumException;
 
+/**
+ * The requested image within the image archive does not exist.
+ *
+ * @author Markus Günther ([email protected])
+ */
 public class ImageDoesNotExistException extends PhotoalbumException {
 
  private static final String ERROR_MESSAGE = "The image file for photo with ID %s does not exist on the filesystem.";