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.krad.data.metadata;
017
018import com.google.common.annotations.Beta;
019import org.kuali.rice.krad.data.provider.annotation.UifAutoCreateViewType;
020
021import java.util.Collection;
022import java.util.List;
023
024
025/**
026* Metadata for a given data object type.
027*
028* <p>
029* References the data object class and contains lists of all the attributes, collections, and relationships within
030* the class.
031* </p>
032*
033* @author Kuali Rice Team (rice.collab@kuali.org)
034*/
035public interface DataObjectMetadata extends MetadataCommon {
036
037    /**
038    * Gets metadata object type.
039    *
040    * <p>
041    * The type represented by this metadata object. Usually this will simply contain the class name created
042    * by the persistence layer when it is loaded from the database.
043    * </p>
044    *
045    * @return metadata object type. Will never return null.
046    */
047        Class<?> getType();
048
049    /**
050    * Gets attributes defined on the data object.
051    *
052    * <p>
053    * Gets all the attributes defined on the data object in the order given by the MetadataProvider. This may or may not
054    * be the same as the backing object's (table) and is most likely the order in which they appear in the source
055    * persistence metadata (XML or annotations).
056    * </p>
057    *
058    * @return Data object attributes. Will never return null. Will return an empty list if no attributes defined.
059    */
060        List<DataObjectAttribute> getAttributes();
061
062    /**
063    * Gets child collections.
064    *
065    * <p>
066    * Gets all the child collections defined on the data object in the order given by the MetadataProvider.
067    * </p>
068    *
069    * @return Child collections. Will never return null. Will return an empty list if no collections defined.
070    */
071        List<DataObjectCollection> getCollections();
072
073    /**
074    * Gets child relationships.
075    *
076    * <p>
077    * Gets all the child relationships defined on the data object in the order given by the MetadataProvider.
078    * </p>
079    *
080    * @return Child relationships. Will never return null. Will return an empty list if no relationships defined.
081    */
082        List<DataObjectRelationship> getRelationships();
083
084    /**
085    * Gets attribute metadata.
086    *
087    * <p>
088    * Get the named attribute's metadata from the data object.
089    * </p>
090    *
091    * @return <b>null</b> if the attributeName does not exist, the associated {@link DataObjectAttribute} otherwise.
092    */
093        DataObjectAttribute getAttribute(String attributeName);
094
095    /**
096    * Gets the named collection's metadata from the data object.
097    *
098    * <p>
099    * The name is the property on the data object which holds
100    * the {@link Collection}.
101    * </p>
102    *
103    * @return <b>null</b> if the attributeName does not exist, the associated {@link DataObjectCollection} otherwise.
104    */
105        DataObjectCollection getCollection(String collectionName);
106
107    /**
108    * Gets the named relationship's metadata from the data object.
109    *
110    * <p>
111    * The name is the property on the data object which holds the related business object's instance.
112    * </p>
113    *
114    * @return <b>null</b> if the attributeName does not exist, the associated {@link DataObjectRelationship} otherwise.
115    */
116        DataObjectRelationship getRelationship(String relationshipName);
117
118    /**
119    * Gets attribute relationships.
120    *
121    * <p>
122    * Returns all relationships of which the given attribute is part of the foreign key relationship.
123    * </p>
124    *
125    * @return The list of relationship metadata objects or an empty list if none found.
126    */
127        List<DataObjectRelationship> getRelationshipsInvolvingAttribute(String attributeName);
128
129        /**
130         * Gets relationship of last attribute.
131     *
132     * <p>
133     * Returns a single relationship for which the given attribute is the last in the foreign key relationship.
134         * </p>
135     *
136         * @return <b>null</b> if no relationship's foreign key set ends wit the given field. The
137         *         {@link DataObjectRelationship} otherwise.
138         */
139        DataObjectRelationship getRelationshipByLastAttributeInRelationship(String attributeName);
140
141    /**
142    * Get the list of primary key attribute names for this data object.
143    *
144    * @return primary key attribute names.
145    */
146    List<String> getPrimaryKeyAttributeNames();
147
148    /**
149    * List of attribute names which form a "user friendly" key. (As opposed to a sequence number as used by some parts
150    * of the system).
151    *
152    * <p>
153    * An example here would be the KIM Role object where the Role ID is the primary key, but the Namespace and Name
154    * properties form the user-visible and enterable key.
155    * </p>
156    *
157    * @return a list containing the business key attributes names for the data object.
158    */
159        List<String> getBusinessKeyAttributeNames();
160
161    /**
162    * Returns true if the list of primary key names and business key attribute names are different.
163    *
164    * @return true if the list of primary key names and business key attributes are different, false if they are the
165    *         same.
166    */
167        Boolean hasDistinctBusinessKey();
168
169    /**
170     * Gets primary display attribute name
171     *
172     * <p>
173     * This is the field on the object which best represents it on displays.  It will be used to build
174     * inquiry links and determine where to place quickfinder links.  Usually this will be the the primary key
175     * or the last field of the primary key if there are multiple fields.
176     * </p>
177     * <p>
178     * If not specified by the provider, the base implementation will default it to the last attribute in the
179     * primaryKeyAttributeNames list.
180     * </p>
181     *
182     * @return the name of the attribute to use for primary display purposes.
183     */
184    String getPrimaryDisplayAttributeName(); // KNS: titleAttribute
185
186    /**
187    * Determines whether optimistic locking is supported.
188    *
189    * <p>
190    * Returns true if the underlying ORM tool performs optimistic locking checks on this object before saving. Under
191    * the KNS, this was done via the versionNumber property and appropriate OJB configuration. In JPA, this is linked
192    * to the @Version annotation.
193    * </p>
194    *
195    * @return true if this data object is configured for optimistic locking.
196    */
197        boolean isSupportsOptimisticLocking();
198
199    /**
200    * BETA: Gets auto create uif view types.
201    *
202    * <p>
203    * Returns collections of uif view types that should be auto created.
204    * </p>
205    *
206    * @return collection of uif view types.
207    */
208    @Beta
209        Collection<UifAutoCreateViewType> getAutoCreateUifViewTypes();
210
211    /**
212    * BETA: Determines where view type should be auto created.
213    *
214    * <p>
215    * Determines whether the specified uif view type can be auto created.
216    * </p>
217    *
218    * @return true if this uif view type should be auto created.
219    */
220    @Beta
221        boolean shouldAutoCreateUifViewOfType(UifAutoCreateViewType viewType);
222}