Merged FILE-FOLDER-API (5.2.0) to HEAD (5.2)

122327 jkaabimofrad: RA-673, RA-678: Added node's renditions REST API. 
                 - Retrieve Renditions For Node + tests
                 - Create Rendition


git-svn-id: https://svn.alfresco.com/repos/alfresco-enterprise/alfresco/HEAD/root@126468 c4b6b30b-aa2e-2d43-bbcb-ca4b014f7261

source/java/org/alfresco/rest/api/Nodes.java

@@ -168,4 +168,13 @@ public interface Nodes
     NodeRef validateNode(NodeRef nodeRef);
     boolean nodeMatches(NodeRef nodeRef, Set<QName> expectedTypes, Set<QName> excludedTypes);
 
+    /**
+     * Determines whether the type of the given nodeRef is a sub-class of another class or not.
+     *
+     * @param nodeRef         source nodeRef
+     * @param ofClassQName    the class to test against
+     * @param validateNodeRef whether to validate the given source node or not
+     * @return true if the type of the given nodeRef is a sub-class of another class, otherwise false
+     */
+    boolean isSubClass(NodeRef nodeRef, QName ofClassQName, boolean validateNodeRef);
 }

source/java/org/alfresco/rest/api/Renditions.java

@@ -0,0 +1,50 @@
+/*
+ * Copyright (C) 2005-2016 Alfresco Software Limited.
+ *
+ * This file is part of Alfresco
+ *
+ * Alfresco is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Alfresco is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with Alfresco. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package org.alfresco.rest.api;
+
+import org.alfresco.rest.api.model.Rendition;
+import org.alfresco.rest.framework.resource.parameters.CollectionWithPagingInfo;
+import org.alfresco.rest.framework.resource.parameters.Parameters;
+
+/**
+ * Renditions API
+ *
+ * @author Jamal Kaabi-Mofrad
+ */
+public interface Renditions
+{
+    /**
+     * Lists all available renditions includes those that have been created and those that are yet to be created.
+     *
+     * @param nodeId     the source node id
+     * @param parameters the {@link Parameters} object to get the parameters passed into the request
+     * @return the rendition results
+     */
+    CollectionWithPagingInfo<Rendition> getRenditions(String nodeId, Parameters parameters);
+
+    /**
+     * Creates a rendition for the given node asynchronously.
+     *
+     * @param nodeId     the source node id
+     * @param rendition  the {@link Rendition} request
+     * @param parameters the {@link Parameters} object to get the parameters passed into the request
+     */
+    void createRendition(String nodeId, Rendition rendition, Parameters parameters);
+}

source/java/org/alfresco/rest/api/impl/NodesImpl.java

@@ -328,6 +328,16 @@ public class NodesImpl implements Nodes
         return nodeMatches(nodeRef, expectedTypes, excludedTypes, true);
     }
 
+    @Override
+    public boolean isSubClass(NodeRef nodeRef, QName ofClassQName, boolean validateNodeRef)
+    {
+        if (validateNodeRef)
+        {
+            nodeRef = validateNode(nodeRef);
+        }
+        return isSubClass(getNodeType(nodeRef), ofClassQName);
+    }
+
     private boolean nodeMatches(NodeRef nodeRef, Set<QName> expectedTypes, Set<QName> excludedTypes, boolean existsCheck)
     {
         if (existsCheck && (! nodeService.exists(nodeRef)))

source/java/org/alfresco/rest/api/impl/RenditionsImpl.java

@@ -0,0 +1,236 @@
+/*
+ * Copyright (C) 2005-2016 Alfresco Software Limited.
+ *
+ * This file is part of Alfresco
+ *
+ * Alfresco is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Alfresco is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with Alfresco. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package org.alfresco.rest.api.impl;
+
+import org.alfresco.model.ContentModel;
+import org.alfresco.query.PagingResults;
+import org.alfresco.repo.thumbnail.ThumbnailDefinition;
+import org.alfresco.repo.thumbnail.ThumbnailHelper;
+import org.alfresco.repo.thumbnail.ThumbnailRegistry;
+import org.alfresco.rest.antlr.WhereClauseParser;
+import org.alfresco.rest.api.Nodes;
+import org.alfresco.rest.api.Renditions;
+import org.alfresco.rest.api.model.ContentInfo;
+import org.alfresco.rest.api.model.Rendition;
+import org.alfresco.rest.api.model.Rendition.RenditionStatus;
+import org.alfresco.rest.framework.core.exceptions.InvalidArgumentException;
+import org.alfresco.rest.framework.resource.parameters.CollectionWithPagingInfo;
+import org.alfresco.rest.framework.resource.parameters.Paging;
+import org.alfresco.rest.framework.resource.parameters.Parameters;
+import org.alfresco.rest.framework.resource.parameters.where.Query;
+import org.alfresco.rest.framework.resource.parameters.where.QueryHelper;
+import org.alfresco.rest.workflow.api.impl.MapBasedQueryWalker;
+import org.alfresco.service.ServiceRegistry;
+import org.alfresco.service.cmr.action.Action;
+import org.alfresco.service.cmr.action.ActionService;
+import org.alfresco.service.cmr.rendition.RenditionService;
+import org.alfresco.service.cmr.repository.ChildAssociationRef;
+import org.alfresco.service.cmr.repository.ContentData;
+import org.alfresco.service.cmr.repository.MimetypeService;
+import org.alfresco.service.cmr.repository.NodeRef;
+import org.alfresco.service.cmr.repository.NodeService;
+import org.alfresco.service.cmr.thumbnail.ThumbnailService;
+import org.alfresco.util.PropertyCheck;
+
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.TreeMap;
+
+/**
+ * @author Jamal Kaabi-Mofrad
+ */
+public class RenditionsImpl implements Renditions
+{
+    private static final String PARAM_status = "status";
+    private static final Set<String> RENDITION_STATUS_COLLECTION_EQUALS_QUERY_PROPERTIES = Collections.singleton(PARAM_status);
+
+    private Nodes nodes;
+    private NodeService nodeService;
+    private ThumbnailService thumbnailService;
+    private RenditionService renditionService;
+    private MimetypeService mimetypeService;
+    private ActionService actionService;
+    private ServiceRegistry serviceRegistry;
+
+    public void setNodes(Nodes nodes)
+    {
+        this.nodes = nodes;
+    }
+
+    public void setThumbnailService(ThumbnailService thumbnailService)
+    {
+        this.thumbnailService = thumbnailService;
+    }
+
+    public void setServiceRegistry(ServiceRegistry serviceRegistry)
+    {
+        this.serviceRegistry = serviceRegistry;
+    }
+
+    public void init()
+    {
+        PropertyCheck.mandatory(this, "nodes", nodes);
+        PropertyCheck.mandatory(this, "thumbnailService", thumbnailService);
+        PropertyCheck.mandatory(this, "serviceRegistry", serviceRegistry);
+
+        this.nodeService = serviceRegistry.getNodeService();
+        this.actionService = serviceRegistry.getActionService();
+        this.renditionService = serviceRegistry.getRenditionService();
+        this.mimetypeService = serviceRegistry.getMimetypeService();
+    }
+
+    @Override
+    public CollectionWithPagingInfo<Rendition> getRenditions(String nodeId, Parameters parameters)
+    {
+        final NodeRef nodeRef = nodes.validateNode(nodeId);
+        if (!nodes.isSubClass(nodeRef, ContentModel.PROP_CONTENT, false))
+        {
+            throw new InvalidArgumentException("Node id '" + nodeId + "' does not represent a file.");
+        }
+
+        ContentData contentData = (ContentData) nodeService.getProperty(nodeRef, ContentModel.PROP_CONTENT);
+        String contentMimeType = contentData.getMimetype();
+
+        Query query = parameters.getQuery();
+        boolean includeCreated = true;
+        boolean includeNotCreated = true;
+        if (query != null)
+        {
+            // Filtering via "where" clause
+            MapBasedQueryWalker propertyWalker = new MapBasedQueryWalker(RENDITION_STATUS_COLLECTION_EQUALS_QUERY_PROPERTIES, null);
+            QueryHelper.walk(query, propertyWalker);
+
+            String withStatus = propertyWalker.getProperty(PARAM_status, WhereClauseParser.EQUALS);
+            if (withStatus != null)
+            {
+                try
+                {
+                    includeCreated = RenditionStatus.CREATED.equals(RenditionStatus.valueOf(withStatus));
+                }
+                catch (IllegalArgumentException ex)
+                {
+                    throw new InvalidArgumentException("Invalid status value: " + withStatus);
+                }
+                includeNotCreated = !includeCreated;
+            }
+        }
+
+        Map<String, Rendition> apiRenditions = new TreeMap<>();
+        if (includeNotCreated)
+        {
+            // List all available thumbnail definitions
+            List<ThumbnailDefinition> thumbnailDefinitions = thumbnailService.getThumbnailRegistry().getThumbnailDefinitions(contentMimeType, -1);
+            for (ThumbnailDefinition thumbnailDefinition : thumbnailDefinitions)
+            {
+                ContentInfo contentInfo = new ContentInfo(thumbnailDefinition.getMimetype(),
+                            getMimeTypeDisplayName(thumbnailDefinition.getMimetype()), null, null);
+                Rendition apiRendition = new Rendition();
+                apiRendition.setId(thumbnailDefinition.getName());
+                apiRendition.setContent(contentInfo);
+                apiRendition.setStatus(RenditionStatus.NOT_CREATED);
+                apiRenditions.put(thumbnailDefinition.getName(), apiRendition);
+            }
+        }
+
+        List<ChildAssociationRef> nodeRefRenditions = renditionService.getRenditions(nodeRef);
+        if (!nodeRefRenditions.isEmpty())
+        {
+            for (ChildAssociationRef childAssociationRef : nodeRefRenditions)
+            {
+                NodeRef renditionNodeRef = childAssociationRef.getChildRef();
+                Rendition apiRendition = toApiRendition(renditionNodeRef);
+                if (includeCreated)
+                {
+                    // Replace/append any thumbnail definitions with created rendition info
+                    apiRenditions.put(apiRendition.getId(), apiRendition);
+                }
+                else
+                {
+                    // Remove any thumbnail definitions that has been created from the list,
+                    // as the filter requires only the Not_Created renditions
+                    apiRenditions.remove(apiRendition.getId());
+                }
+            }
+        }
+
+        // Wrap paging info, as the core service doesn't support paging
+        Paging paging = parameters.getPaging();
+        PagingResults<Rendition> results = Util.wrapPagingResults(paging, apiRenditions.values());
+
+        return CollectionWithPagingInfo.asPaged(paging, results.getPage(), results.hasMoreItems(), results.getTotalResultCount().getFirst());
+    }
+
+    @Override
+    public void createRendition(String nodeId, Rendition rendition, Parameters parameters)
+    {
+        NodeRef sourceNodeRef = nodes.validateNode(nodeId);
+
+        // If thumbnail generation has been configured off, then don't bother with any of this.
+        if (thumbnailService.getThumbnailsEnabled())
+        {
+            // Use the thumbnail registry to get the details of the thumbnail
+            ThumbnailRegistry registry = thumbnailService.getThumbnailRegistry();
+            ThumbnailDefinition details = registry.getThumbnailDefinition(rendition.getId());
+            if (details == null)
+            {
+                // Throw exception
+                throw new InvalidArgumentException("The thumbnail name '" + rendition.getId() + "' is not registered");
+            }
+
+            // Check if anything is currently registered to generate thumbnails for the specified mimeType
+            ContentData contentData = (ContentData) nodeService.getProperty(sourceNodeRef, ContentModel.PROP_CONTENT);
+            if (!ContentData.hasContent(contentData))
+            {
+                throw new InvalidArgumentException("Unable to create thumbnail '" + details.getName() + "' as there is no content");
+            }
+            if (!registry.isThumbnailDefinitionAvailable(contentData.getContentUrl(), contentData.getMimetype(), contentData.getSize(), sourceNodeRef, details))
+            {
+                throw new InvalidArgumentException("Unable to create thumbnail '" + details.getName() + "' for " +
+                            contentData.getMimetype() + " as no transformer is currently available.");
+            }
+
+            Action action = ThumbnailHelper.createCreateThumbnailAction(details, serviceRegistry);
+            // Queue async creation of thumbnail
+            actionService.executeAction(action, sourceNodeRef, true, true);
+        }
+    }
+
+    protected Rendition toApiRendition(NodeRef renditionNodeRef)
+    {
+        Rendition apiRendition = new Rendition();
+
+        String renditionName = (String) nodeService.getProperty(renditionNodeRef, ContentModel.PROP_NAME);
+        apiRendition.setId(renditionName);
+
+        ContentData contentData = (ContentData) nodeService.getProperty(renditionNodeRef, ContentModel.PROP_CONTENT);
+        ContentInfo contentInfo = new ContentInfo(contentData.getMimetype(), getMimeTypeDisplayName(contentData.getMimetype()), contentData.getSize(), contentData.getEncoding());
+        apiRendition.setContent(contentInfo);
+        apiRendition.setStatus(RenditionStatus.CREATED);
+
+        return apiRendition;
+    }
+
+    private String getMimeTypeDisplayName(String mimeType)
+    {
+        return mimetypeService.getDisplaysByMimetype().get(mimeType);
+    }
+}

source/java/org/alfresco/rest/api/impl/Util.java

@@ -1,23 +1,5 @@
 /*
- * Copyright (C) 2005-2012 Alfresco Software Limited.
- *
- * This file is part of Alfresco
- *
- * Alfresco is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Lesser General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * Alfresco is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * along with Alfresco. If not, see <http://www.gnu.org/licenses/>.
- */
-/*
- * Copyright (C) 2005-2012 Alfresco Software Limited.
+ * Copyright (C) 2005-2016 Alfresco Software Limited.
  *
  * This file is part of Alfresco
  *
@@ -34,18 +16,94 @@
  * You should have received a copy of the GNU Lesser General Public License
  * along with Alfresco. If not, see <http://www.gnu.org/licenses/>.
  */
+
 package org.alfresco.rest.api.impl;
 
 import org.alfresco.query.CannedQueryPageDetails;
+import org.alfresco.query.PageDetails;
 import org.alfresco.query.PagingRequest;
+import org.alfresco.query.PagingResults;
+import org.alfresco.rest.framework.core.exceptions.InvalidArgumentException;
 import org.alfresco.rest.framework.resource.parameters.Paging;
+import org.alfresco.util.Pair;
 
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.Iterator;
+import java.util.List;
+
+/**
+ * @author steveglover
+ * @author Jamal Kaabi-Mofrad
+ */
 public class Util
 {
-	public static PagingRequest getPagingRequest(Paging paging)
+    public static PagingRequest getPagingRequest(Paging paging)
     {
-    	PagingRequest pagingRequest = new PagingRequest(paging.getSkipCount(), paging.getMaxItems());
-    	pagingRequest.setRequestTotalCountMax(CannedQueryPageDetails.DEFAULT_PAGE_SIZE);
-    	return pagingRequest;
+        PagingRequest pagingRequest = new PagingRequest(paging.getSkipCount(), paging.getMaxItems());
+        pagingRequest.setRequestTotalCountMax(CannedQueryPageDetails.DEFAULT_PAGE_SIZE);
+        return pagingRequest;
+    }
+
+    public static <T> PagingResults<T> wrapPagingResults(Paging paging, Collection<T> result)
+    {
+        if (paging == null)
+        {
+            throw new InvalidArgumentException("paging object can't be null.");
+        }
+        if (result == null)
+        {
+            result = Collections.emptyList();
+        }
+
+        PagingRequest pagingRequest = getPagingRequest(paging);
+
+        final int totalSize = result.size();
+        final PageDetails pageDetails = PageDetails.getPageDetails(pagingRequest, totalSize);
+
+        final List<T> page = new ArrayList<>(pageDetails.getPageSize());
+        Iterator<T> it = result.iterator();
+        for (int counter = 0, end = pageDetails.getEnd(); counter < end && it.hasNext(); counter++)
+        {
+            T element = it.next();
+            if (counter < pageDetails.getSkipCount())
+            {
+                continue;
+            }
+            if (counter > end - 1)
+            {
+                break;
+            }
+            page.add(element);
+        }
+
+        return new PagingResults<T>()
+        {
+            @Override
+            public List<T> getPage()
+            {
+                return page;
+            }
+
+            @Override
+            public boolean hasMoreItems()
+            {
+                return pageDetails.hasMoreItems();
+            }
+
+            @Override
+            public Pair<Integer, Integer> getTotalResultCount()
+            {
+                Integer total = totalSize;
+                return new Pair<>(total, total);
+            }
+
+            @Override
+            public String getQueryExecutionId()
+            {
+                return null;
+            }
+        };
     }
 }

source/java/org/alfresco/rest/api/model/Rendition.java

@@ -0,0 +1,79 @@
+/*
+ * Copyright (C) 2005-2016 Alfresco Software Limited.
+ *
+ * This file is part of Alfresco
+ *
+ * Alfresco is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Alfresco is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with Alfresco. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package org.alfresco.rest.api.model;
+
+/**
+ * Representation of a rendition.
+ *
+ * @author Jamal Kaabi-Mofrad
+ */
+public class Rendition
+{
+    public enum RenditionStatus
+    {
+        CREATED,
+        NOT_CREATED
+    }
+
+    private String id;
+    private RenditionStatus status;
+    private ContentInfo contentInfo;
+
+    public String getId()
+    {
+        return id;
+    }
+
+    public void setId(String id)
+    {
+        this.id = id;
+    }
+
+    public RenditionStatus getStatus()
+    {
+        return status;
+    }
+
+    public void setStatus(RenditionStatus status)
+    {
+        this.status = status;
+    }
+
+    public ContentInfo getContent()
+    {
+        return contentInfo;
+    }
+
+    public void setContent(ContentInfo contentInfo)
+    {
+        this.contentInfo = contentInfo;
+    }
+
+    @Override
+    public String toString()
+    {
+        final StringBuilder sb = new StringBuilder(150);
+        sb.append("Rendition [id='").append(id)
+                    .append(", status=").append(status)
+                    .append(", contentInfo=").append(contentInfo)
+                    .append(']');
+        return sb.toString();
+    }
+}

source/java/org/alfresco/rest/api/nodes/NodeRenditionsRelation.java

@@ -0,0 +1,73 @@
+/*
+ * Copyright (C) 2005-2016 Alfresco Software Limited.
+ *
+ * This file is part of Alfresco
+ *
+ * Alfresco is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Alfresco is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with Alfresco. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package org.alfresco.rest.api.nodes;
+
+import org.alfresco.rest.api.Renditions;
+import org.alfresco.rest.api.model.Rendition;
+import org.alfresco.rest.framework.resource.RelationshipResource;
+import org.alfresco.rest.framework.resource.actions.interfaces.RelationshipResourceAction;
+import org.alfresco.rest.framework.resource.parameters.CollectionWithPagingInfo;
+import org.alfresco.rest.framework.resource.parameters.Parameters;
+import org.alfresco.util.PropertyCheck;
+import org.springframework.beans.factory.InitializingBean;
+
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * Node renditions.
+ *
+ * @author Jamal Kaabi-Mofrad
+ */
+@RelationshipResource(name = "renditions", entityResource = NodesEntityResource.class, title = "Node renditions")
+public class NodeRenditionsRelation implements RelationshipResourceAction.Read<Rendition>,
+            RelationshipResourceAction.Create<Rendition>,
+            InitializingBean
+{
+
+    private Renditions renditions;
+
+    public void setRenditions(Renditions renditions)
+    {
+        this.renditions = renditions;
+    }
+
+    @Override
+    public void afterPropertiesSet() throws Exception
+    {
+        PropertyCheck.mandatory(this, "renditions", renditions);
+    }
+
+    @Override
+    public CollectionWithPagingInfo<Rendition> readAll(String nodeId, Parameters parameters)
+    {
+        return renditions.getRenditions(nodeId, parameters);
+    }
+
+    @Override
+    public List<Rendition> create(String nodeId, List<Rendition> entity, Parameters parameters)
+    {
+        for (Rendition rendition : entity)
+        {
+            renditions.createRendition(nodeId, rendition, parameters);
+        }
+        return Collections.emptyList();
+    }
+}