001/**
002 * Copyright 2005-2016 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.api.document.attribute;
017
018import org.apache.commons.lang.StringUtils;
019import org.kuali.rice.core.api.CoreConstants;
020import org.kuali.rice.core.api.mo.AbstractDataTransferObject;
021import org.kuali.rice.core.api.mo.ModelBuilder;
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.XmlSeeAlso;
029import javax.xml.bind.annotation.XmlType;
030import java.io.Serializable;
031import java.util.Collection;
032
033/**
034 * An abstract representation of the {@code DocumentAttributeContract} which can be used as the super class for
035 * concrete immutable data transfer object implementations of document attributes.  This class also defines an abstract
036 * builder implementation which can be extended by it's subclasses to create their own internal builder implementations.
037 *
038 * <p>The KEW api defines the understood set of document attribute implementations, so it is not generally of value for
039 * a client of the api to subclass this class.</p>
040 *
041 * @author Kuali Rice Team (rice.collab@kuali.org).
042 */
043@XmlAccessorType(XmlAccessType.NONE)
044@XmlType(name = DocumentAttribute.Constants.TYPE_NAME, propOrder = {
045    DocumentAttribute.Elements.NAME,
046    CoreConstants.CommonElements.FUTURE_ELEMENTS
047})
048@XmlSeeAlso( { DocumentAttributeString.class, DocumentAttributeDateTime.class, DocumentAttributeInteger.class, DocumentAttributeDecimal.class } )
049public abstract class DocumentAttribute extends AbstractDataTransferObject implements DocumentAttributeContract {
050
051    private static final long serialVersionUID = -1935235225791818090L;
052    
053    @XmlElement(name = Elements.NAME, required = true)
054    private final String name;
055
056    @SuppressWarnings("unused")
057    @XmlAnyElement
058    private final Collection<Element> _futureElements = null;
059
060    protected DocumentAttribute() {
061        this.name = null;
062    }
063
064    DocumentAttribute(String name) {
065        if (StringUtils.isBlank(name)) {
066            throw new IllegalArgumentException("name was null or blank");
067        }
068        this.name = name;
069    }
070
071    @Override
072    public String getName() {
073        return name;
074    }
075
076    /**
077     * An abstract base class that can be extended by concrete builder implementations of subclasses of
078     * {@code DocumentAttribute}.
079     *
080     * @param <T> the type of the value contained within the document attribute that is built by this builder
081     */
082    public abstract static class AbstractBuilder<T> implements Serializable, ModelBuilder, DocumentAttributeContract {
083
084        private static final long serialVersionUID = -4402662354421207678L;
085        
086        private String name;
087        private T value;
088
089        protected AbstractBuilder(String name) {
090            setName(name);
091        }
092
093        @Override
094        public String getName() {
095            return name;
096        }
097
098        /**
099         * Sets the name of the document attribute that will be built by this builder.
100         *
101         * @param name the name of the document attribute to set, must not be a null or blank value
102         * @throws IllegalArgumentException if the given name is a null or blank value.
103         */
104        public void setName(String name) {
105            if (StringUtils.isBlank(name)) {
106                throw new IllegalArgumentException("name was null or blank");
107            }
108            this.name = name;
109        }
110
111        @Override
112        public T getValue() {
113            return value;
114        }
115
116        /**
117         * Sets the value of the document attribute that will be built by this builder.
118         *
119         * @param value the value of the document attribute to set
120         */
121        public void setValue(T value) {
122            this.value = value;
123        }
124
125        /**
126         * Build the {@code DocumentAttribute} for this builder based on it's current state.
127         *
128         * @return the instantiated instance of {@code DocumentAttribute} which was built by this builder
129         */
130        public abstract DocumentAttribute build();
131        
132    }
133
134    /**
135     * Defines some internal constants used on this class.
136     */
137    static class Constants {
138        final static String TYPE_NAME = "DocumentAttributeType";
139    }
140
141    /**
142     * A private class which exposes constants which define the XML element names to use when this object is marshalled to XML.
143     */
144    static class Elements {
145        final static String NAME = "name";
146    }
147
148}