CCM NG:

- Added some more JavaDoc
- Replaced return values in CcmObjectRepository with Optional for methods which not return a value


git-svn-id: https://svn.libreccm.org/ccm/ccm_ng@4234 8810af33-2d31-482b-a856-94f89814c4df

ccm-cms/src/main/java/org/librecms/contentsection/ContentItemManager.java

@@ -63,6 +63,7 @@ import javax.persistence.TypedQuery;
 import javax.transaction.Transactional;
 
 /**
+ * Manager class providing several methods to manipulate {@link ContentItem}s.
  *
  * @author <a href="mailto:jens.pelzetter@googlemail.com">Jens Pelzetter</a>
  */
@@ -151,8 +152,7 @@ public class ContentItemManager {
      *
      * @param <T> The type of the content item.
      * @param name The name (URL stub) of the new content item.
-     * @param section             The content section in which the item is
+     * @param section The content section in which the item is generated.
-     *                            generated.
      * @param folder The folder in which in the item is stored.
      * @param workflowTemplate
      * @param lifecycleDefinition
@@ -243,15 +243,15 @@ public class ContentItemManager {
      *
      * @param item The item to copy.
      * @param targetFolder The folder in which the copy is created. If the
-     *                     target folder is the same folder as the folder of the
+     * target folder is the same folder as the folder of the original item an
-     *                     original item an index is appended to the name of the
+     * index is appended to the name of the item.
-     *                     item.
      */
     @SuppressWarnings("unchecked")
     public void copy(final ContentItem item, final Category targetFolder) {
         final Optional<ContentType> contentType = typeRepo
                 .findByContentSectionAndClass(
-                item.getContentType().getContentSection(), item.getClass());
+                        item.getContentType().getContentSection(), item.
+                        getClass());
 
         if (!contentType.isPresent()) {
             throw new IllegalArgumentException(String.format(
@@ -332,7 +332,8 @@ public class ContentItemManager {
                 }
 
                 source.getAvailableLocales().forEach(
-                    locale -> target.addValue(locale, source.getValue(locale)));
+                        locale -> target.addValue(locale, source.
+                                                  getValue(locale)));
             } else if (propType != null
                                && propType.isAssignableFrom(ContentItem.class)) {
 
@@ -499,7 +500,8 @@ public class ContentItemManager {
                 }
 
                 source.getAvailableLocales().forEach(
-                    locale -> target.addValue(locale, source.getValue(locale)));
+                        locale -> target.addValue(locale, source.
+                                                  getValue(locale)));
             } else if (propType != null
                                && propType.isAssignableFrom(ContentItem.class)) {
                 final ContentItem linkedItem;
@@ -587,7 +589,8 @@ public class ContentItemManager {
     }
 
     /**
-     * Unpublishes a content item by deleting its live version if any.
+     * Unpublishes a content item by deleting its live version if there is a
+     * live version.
      *
      * @param item
      */
@@ -627,9 +630,9 @@ public class ContentItemManager {
      * @param type Type of the content item.
      *
      * @return The live version of an item. If the item provided is already the
-     *         live version the provided item is returned, otherwise the live
+     * live version the provided item is returned, otherwise the live version is
-     *         version is returned. If there is no live version an empty
+     * returned. If there is no live version an empty {@link Optional} is
-     *         {@link Optional} is returned.
+     * returned.
      */
     public <T extends ContentItem> Optional<T> getLiveVersion(
             final ContentItem item,
@@ -669,10 +672,10 @@ public class ContentItemManager {
      * @param type Type of the item.
      *
      * @return The draft version of the provided content item. If the provided
-     *         item is the draft version the provided item is simply returned.
+     * item is the draft version the provided item is simply returned. Otherwise
-     *         Otherwise the draft version is retrieved from the database and is
+     * the draft version is retrieved from the database and is returned. Each
-     *         returned. Each content item has a draft version (otherwise
+     * content item has a draft version (otherwise something is seriously wrong
-     *         something is seriously wrong with the database) this method will
+     * with the database) this method will
      * <b>never</b> return {@code null}.
      */
     public <T extends ContentItem> T getDraftVersion(final ContentItem item,

ccm-cms/src/main/java/org/librecms/contentsection/ContentItemRepository.java

@@ -23,15 +23,12 @@ import org.libreccm.categorization.Category;
 import org.libreccm.core.CcmObject;
 import org.libreccm.core.CcmObjectRepository;
 
-import java.util.ArrayList;
 import java.util.List;
 import java.util.Optional;
-import java.util.stream.Collectors;
 
 import javax.enterprise.context.RequestScoped;
 import javax.inject.Inject;
 import javax.persistence.TypedQuery;
-import jdk.nashorn.internal.objects.NativeArray;
 
 /**
  * Repository for content items.
@@ -69,9 +66,9 @@ public class ContentItemRepository
      * nothing if there is such content item.
      */
     public Optional<ContentItem> findById(final long itemId) {
-        final CcmObject result = ccmObjectRepo.findObjectById(itemId);
+        final Optional<CcmObject> result = ccmObjectRepo.findObjectById(itemId);
-        if (result instanceof ContentItem) {
+        if (result.isPresent() && result.get() instanceof ContentItem) {
-            return Optional.of((ContentItem) result);
+            return Optional.of((ContentItem) result.get());
         } else {
             return Optional.empty();
         }
@@ -107,12 +104,12 @@ public class ContentItemRepository
      * @return The content item identified by the provided {@code uuid} or
      * nothing if there is such content item.
      */
-    public ContentItem findByUuid(final String uuid) {
+    public Optional<ContentItem> findByUuid(final String uuid) {
-        final CcmObject result = ccmObjectRepo.findObjectByUuid(uuid);
+        final Optional<CcmObject> result = ccmObjectRepo.findObjectByUuid(uuid);
-        if (result instanceof ContentItem) {
+        if (result.isPresent() && result.get() instanceof ContentItem) {
-            return (ContentItem) result;
+            return Optional.of((ContentItem) result.get());
         } else {
-            return null;
+            return Optional.empty();
         }
     }
 
@@ -131,10 +128,11 @@ public class ContentItemRepository
     @SuppressWarnings("unchecked")
     public <T extends ContentItem> Optional<T> findByUuid(final String uuid,
                                                           final Class<T> type) {
-        final CcmObject result = ccmObjectRepo.findObjectByUuid(uuid);
+        final Optional<CcmObject> result = ccmObjectRepo.findObjectByUuid(uuid);
 
-        if (result.getClass().isAssignableFrom(type)) {
+        if (result.isPresent() 
-            return Optional.of((T) result);
+            && result.get().getClass().isAssignableFrom(type)) {
+            return Optional.of((T) result.get());
         } else {
             return Optional.empty();
         }
@@ -173,6 +171,12 @@ public class ContentItemRepository
         return query.getResultList();
     }
 
+    /**
+     * Counts the items in a folder/category.
+     *
+     * @param folder The folder/category
+     * @return The number of content items in the category/folder.
+     */
     public long countItemsInFolder(final Category folder) {
         final TypedQuery<Long> query = getEntityManager()
                 .createNamedQuery("ContentItem.countItemsInFolder", Long.class);
@@ -181,6 +185,13 @@ public class ContentItemRepository
         return query.getSingleResult();
     }
 
+    /**
+     * Counts the number of items with a specific name in a folder/category.
+     *
+     * @param folder
+     * @param name
+     * @return
+     */
     public long countByNameInFolder(final Category folder, final String name) {
         final TypedQuery<Long> query = getEntityManager().createNamedQuery(
                 "ContentItem.countByNameInFolder", Long.class);
@@ -190,6 +201,15 @@ public class ContentItemRepository
         return query.getSingleResult();
     }
 
+    /**
+     * Retrieves all items in a specific folder where
+     * {@link CcmObject#displayName} of the item starts with the provided
+     * pattern.
+     *
+     * @param folder The folder/category whose items are filtered.
+     * @param name The name pattern to use.
+     * @return A list with all items in the folder matching the provided filter.
+     */
     public List<ContentItem> filterByFolderAndName(final Category folder,
                                                    final String name) {
         final TypedQuery<ContentItem> query = getEntityManager()
@@ -201,6 +221,15 @@ public class ContentItemRepository
         return query.getResultList();
     }
 
+    /**
+     * Counts a items in a specfic folder whose {@link CcmObject#displayName}
+     * starts with the provided pattern.
+     *
+     * @param folder The folder/category to use.
+     * @param name The name pattern to use.
+     * @return The number of items in the folder/category which match the
+     * provided pattern.
+     */
     public long countFilterByFolderAndName(final Category folder,
                                            final String name) {
         final TypedQuery<Long> query = getEntityManager()

ccm-core/src/main/java/com/arsdigita/ui/admin/usersgroupsroles/roles/RolePermissionsForm.java

@@ -27,6 +27,7 @@ import com.arsdigita.bebop.ParameterSingleSelectionModel;
 import com.arsdigita.bebop.SaveCancelSection;
 import com.arsdigita.bebop.form.TextField;
 import com.arsdigita.globalization.GlobalizedMessage;
+import java.util.Optional;
 
 import org.libreccm.cdi.utils.CdiUtil;
 import org.libreccm.core.CcmObject;
@@ -109,11 +110,11 @@ class RolePermissionsForm extends Form {
         saveCancelSection = new SaveCancelSection();
         add(saveCancelSection);
 
-        addValidationListener(e -> {
+        addValidationListener(event -> {
-            final PageState state = e.getPageState();
+            final PageState state = event.getPageState();
 
             if (saveCancelSection.getSaveButton().isSelected(state)) {
-                final FormData data = e.getFormData();
+                final FormData data = event.getFormData();
 
                 final String privilegeData = data.getString(PRIVILEGE);
                 if (privilegeData == null || privilegeData.isEmpty()) {
@@ -140,9 +141,10 @@ class RolePermissionsForm extends Form {
                         return;
                     }
 
-                    final CcmObject object = objectRepository.findObjectById(
+                    final Optional<CcmObject> object = objectRepository.
+                            findObjectById(
                                     Long.parseLong(objectIdData));
-                    if (object == null) {
+                    if (!object.isPresent()) {
                         data.addError(
                                 OBJECT_ID,
                                 new GlobalizedMessage(
@@ -154,11 +156,11 @@ class RolePermissionsForm extends Form {
             }
         });
 
-        addProcessListener(e -> {
+        addProcessListener(event -> {
-            final PageState state = e.getPageState();
+            final PageState state = event.getPageState();
 
             if (saveCancelSection.getSaveButton().isSelected(state)) {
-                final FormData data = e.getFormData();
+                final FormData data = event.getFormData();
 
                 final String privilegeData = data.getString(PRIVILEGE);
                 final String objectIdData = data.getString(OBJECT_ID);
@@ -176,11 +178,11 @@ class RolePermissionsForm extends Form {
                 } else {
                     final CcmObjectRepository objectRepository = cdiUtil
                             .findBean(CcmObjectRepository.class);
-                    final CcmObject object = objectRepository.findObjectById(
+                    final Optional<CcmObject> object = objectRepository
-                        Long.parseLong(objectIdData));
+                            .findObjectById(Long.parseLong(objectIdData));
                     permissionManager.grantPrivilege(privilegeData,
                                                      role,
-                                                     object);
+                                                     object.get());
                 }
             }
 

ccm-core/src/main/java/org/libreccm/core/CcmObjectRepository.java

@@ -18,6 +18,8 @@
  */
 package org.libreccm.core;
 
+import java.util.Optional;
+
 import static org.libreccm.core.CoreConstants.*;
 
 import java.util.UUID;
@@ -58,27 +60,33 @@ public class CcmObjectRepository extends AbstractEntityRepository<Long, CcmObjec
         entity.setUuid(UUID.randomUUID().toString());
     }
 
-    public CcmObject findObjectById(final long objectId) {
+    /**
+     * Finds a {@link CcmObject} by its id.
+     *
+      @param objectId The id of the item to find.
+     * @return
+     */
+    public Optional<CcmObject> findObjectById(final long objectId) {
         final TypedQuery<CcmObject> query = getEntityManager().createNamedQuery(
                 "CcmObject.findById", CcmObject.class);
         query.setParameter("id", objectId);
 
         try {
-            return query.getSingleResult();
+            return Optional.of(query.getSingleResult());
         } catch (NoResultException ex) {
-            return null;
+            return Optional.empty();
         }
     }
 
-    public CcmObject findObjectByUuid(final String uuid) {
+    public Optional<CcmObject> findObjectByUuid(final String uuid) {
         final TypedQuery<CcmObject> query = getEntityManager().createNamedQuery(
                 "CcmObject.findByUuid", CcmObject.class);
         query.setParameter("uuid", uuid);
 
         try {
-            return query.getSingleResult();
+            return Optional.of(query.getSingleResult());
         } catch (NoResultException ex) {
-            return null;
+            return Optional.empty();
         }
     }