001/**
002 * Copyright 2005-2018 The Kuali Foundation
003 *
004 * Licensed under the Educational Community License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.opensource.org/licenses/ecl2.php
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.kuali.rice.kew.framework.document.security;
017
018import org.apache.commons.collections.CollectionUtils;
019import org.kuali.rice.core.api.CoreConstants;
020import org.kuali.rice.core.api.mo.ModelObjectUtils;
021import org.kuali.rice.kew.api.document.Document;
022import org.w3c.dom.Element;
023
024import javax.xml.bind.annotation.XmlAccessType;
025import javax.xml.bind.annotation.XmlAccessorType;
026import javax.xml.bind.annotation.XmlAnyElement;
027import javax.xml.bind.annotation.XmlElement;
028import javax.xml.bind.annotation.XmlElementWrapper;
029import javax.xml.bind.annotation.XmlRootElement;
030import javax.xml.bind.annotation.XmlType;
031import java.util.Collection;
032import java.util.List;
033
034/**
035 * Defines a directive for processing a list of security attributes against a supplied list of documents.  The names of
036 * these security attributes represent the name of an {@link org.kuali.rice.kew.api.extension.ExtensionDefinition} which
037 * will be used to load the appropriate {@link DocumentSecurityAttribute} implementation in order to perform the security filtering.
038 *
039 * <p>The actual directive is supplied to the appropriate application that is responsible for the given security attributes
040 * by invoking that applications {@link DocumentSecurityHandlerService}.  This class primarily functions as a form of
041 * data transport in order to package and send the required information.</p>
042 *
043 * @see DocumentSecurityAttribute
044 * @see DocumentSecurityHandlerService
045 * @see org.kuali.rice.kew.api.extension.ExtensionDefinition
046 */
047@XmlRootElement(name = DocumentSecurityDirective.Constants.ROOT_ELEMENT_NAME)
048@XmlAccessorType(XmlAccessType.NONE)
049@XmlType(name = DocumentSecurityDirective.Constants.TYPE_NAME, propOrder = {
050    DocumentSecurityDirective.Elements.DOCUMENT_SECURITY_ATTRIBUTE_NAMES,
051    DocumentSecurityDirective.Elements.DOCUMENTS,
052    CoreConstants.CommonElements.FUTURE_ELEMENTS
053})
054public final class DocumentSecurityDirective {
055
056    @XmlElementWrapper(name = Elements.DOCUMENT_SECURITY_ATTRIBUTE_NAMES, required = true)
057    @XmlElement(name = Elements.DOCUMENT_SECURITY_ATTRIBUTE_NAME, required = true)
058    private final List<String> documentSecurityAttributeNames;
059
060    @XmlElementWrapper(name = Elements.DOCUMENTS, required = true)
061    @XmlElement(name = Elements.DOCUMENT, required = true)
062    private final List<Document> documents;
063
064    @SuppressWarnings("unused")
065    @XmlAnyElement
066    private final Collection<Element> _futureElements = null;
067
068    /**
069     * Private constructor used only by JAXB.
070     */
071    @SuppressWarnings("unused")
072    private DocumentSecurityDirective() {
073        this.documentSecurityAttributeNames = null;
074        this.documents = null;
075    }
076
077    private DocumentSecurityDirective(List<String> documentSecurityAttributeNames, List<Document> documents) {
078        if (CollectionUtils.isEmpty(documentSecurityAttributeNames)) {
079            throw new IllegalArgumentException("documentSecurityAttributeNames cannot be null or empty");
080        }
081        this.documentSecurityAttributeNames = ModelObjectUtils.createImmutableCopy(documentSecurityAttributeNames);
082        this.documents = ModelObjectUtils.createImmutableCopy(documents);
083    }
084
085    /**
086     * Creates a new security directive from the given list of document secruity attribute names and documents.
087     *
088     * @param documentSecurityAttributeNames the list of document security attribute names with which to create this
089     * security directive
090     * @param documents the list of documents with which to create this security directive
091     *
092     * @return a new document security directive instance
093     *
094     * @throws IllegalArgumentException if the given list of security attribute names is null or empty
095     */
096    public static DocumentSecurityDirective create(List<String> documentSecurityAttributeNames,
097            List<Document> documents) {
098        return new DocumentSecurityDirective(documentSecurityAttributeNames, documents);
099    }
100
101    /**
102     * Returns the list of document security attribute names on this security directive.  Will never return a null or
103     * empty list.
104     *
105     * @return the list of document security attribute names on this security directive
106     */
107    public List<String> getDocumentSecurityAttributeNames() {
108        return documentSecurityAttributeNames;
109    }
110
111    /**
112     * Returns the list of documents on this security directive.  Will never return null, but may return an empty list.
113     *
114     * @return the list of documents on this security directive
115     */
116    public List<Document> getDocuments() {
117        return documents;
118    }
119
120    /**
121     * Defines some internal constants used on this class.
122     */
123    static class Constants {
124        final static String ROOT_ELEMENT_NAME = "documentSecurityDirective";
125        final static String TYPE_NAME = "DocumentSecurityDirectiveType";
126    }
127
128    /**
129     * A private class which exposes constants which define the XML element names to use when this object is marshalled to XML.
130     */
131    static class Elements {
132        final static String DOCUMENT_SECURITY_ATTRIBUTE_NAMES = "documentSecurityAttributeNames";
133        final static String DOCUMENT_SECURITY_ATTRIBUTE_NAME = "documentSecurityAttributeName";
134        final static String DOCUMENTS = "documents";
135        final static String DOCUMENT = "document";
136    }
137
138}