001    /*
002     * Copyright 2008-2015 UnboundID Corp.
003     * All Rights Reserved.
004     */
005    /*
006     * Copyright (C) 2015 UnboundID Corp.
007     *
008     * This program is free software; you can redistribute it and/or modify
009     * it under the terms of the GNU General Public License (GPLv2 only)
010     * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
011     * as published by the Free Software Foundation.
012     *
013     * This program is distributed in the hope that it will be useful,
014     * but WITHOUT ANY WARRANTY; without even the implied warranty of
015     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
016     * GNU General Public License for more details.
017     *
018     * You should have received a copy of the GNU General Public License
019     * along with this program; if not, see <http://www.gnu.org/licenses>.
020     */
021    package com.unboundid.ldap.sdk.unboundidds.tasks;
022    
023    
024    
025    import java.io.Serializable;
026    import java.util.Date;
027    
028    import com.unboundid.util.NotMutable;
029    import com.unboundid.util.ThreadSafety;
030    import com.unboundid.util.ThreadSafetyLevel;
031    
032    import static com.unboundid.util.Validator.*;
033    
034    
035    
036    /**
037     * <BLOCKQUOTE>
038     *   <B>NOTE:</B>  This class is part of the Commercial Edition of the UnboundID
039     *   LDAP SDK for Java.  It is not available for use in applications that
040     *   include only the Standard Edition of the LDAP SDK, and is not supported for
041     *   use in conjunction with non-UnboundID products.
042     * </BLOCKQUOTE>
043     * This class provides information about a property that may be used to schedule
044     * a task.  Elements of a task property include:
045     * <UL>
046     *   <LI>The name of the LDAP attribute used to store values for this
047     *       property.</LI>
048     *   <LI>A user-friendly display name for the property.</LI>
049     *   <LI>A user-friendly description for the property.</LI>
050     *   <LI>The expected data type for values of the property.</LI>
051     *   <LI>An optional set of allowed values for the property.  If this is
052     *       defined, then the property will not be allowed to have any value that
053     *       is not included in this set.</LI>
054     *   <LI>A flag that indicates whether the property is required when scheduling
055     *       the corresponding type of task.</LI>
056     *   <LI>A flag that indicates whether the property is allowed to have multiple
057     *       values.</LI>
058     *   <LI>A flag that indicates whether the property should be considered
059     *       advanced and therefore may be hidden from users if a simplified
060     *       interface is to be presented.</LI>
061     * </UL>
062     */
063    @NotMutable()
064    @ThreadSafety(level=ThreadSafetyLevel.COMPLETELY_THREADSAFE)
065    public final class TaskProperty
066           implements Serializable
067    {
068      /**
069       * The serial version UID for this serializable class.
070       */
071      private static final long serialVersionUID = 8438462010090371903L;
072    
073    
074    
075      // Indicates whether this task property is advanced.
076      private final boolean advanced;
077    
078      // Indicates whether this task property is multivalued.
079      private final boolean multiValued;
080    
081      // Indicates whether this task property is required.
082      private final boolean required;
083    
084      // The data type for this task property.
085      private final Class<?> dataType;
086    
087      // The set of allowed values for this task property.
088      private final Object[] allowedValues;
089    
090      // The name of the LDAP attribute associated with this task property.
091      private final String attributeName;
092    
093      // The human-readable description for this task property.
094      private final String description;
095    
096      // The human-readable display name for this task property.
097      private final String displayName;
098    
099    
100    
101      /**
102       * Creates a new task property with the provided information.
103       *
104       * @param  attributeName  The name of the LDAP attribute associated with this
105       *                        task property.  It must not be {@code null}.
106       * @param  displayName    The human-readable display name for this task
107       *                        property.  It must not be {@code null}.
108       * @param  description    The human-readable description for this task
109       *                        property.  It must not be {@code null}.
110       * @param  dataType       A class representing the data type for this
111       *                        property.  Allowed data type classes include:
112       *                        {@code Boolean}, {@code Date}, {@code Long}, and
113       *                        {@code String}.  It must not be {@code null}.
114       * @param  required       Indicates whether this property must be provided
115       *                        when scheduling a task.
116       * @param  multiValued    Indicates whether this property is allowed to have
117       *                        multiple values.
118       * @param  advanced       Indicates whether this property may be considered
119       *                        advanced and doesn't necessarily need to be
120       *                        presented to the user.  Advanced properties must not
121       *                        be required.
122       */
123      public TaskProperty(final String attributeName, final String displayName,
124                          final String description, final Class<?> dataType,
125                          final boolean required, final boolean multiValued,
126                          final boolean advanced)
127      {
128        this(attributeName, displayName, description, dataType, required,
129             multiValued, advanced, null);
130      }
131    
132    
133    
134      /**
135       * Creates a new task property with the provided information.
136       *
137       * @param  attributeName  The name of the LDAP attribute associated with this
138       *                        task property.  It must not be {@code null}.
139       * @param  displayName    The human-readable display name for this task
140       *                        property.  It must not be {@code null}.
141       * @param  description    The human-readable description for this task
142       *                        property.  It must not be {@code null}.
143       * @param  dataType       A class representing the data type for this
144       *                        property.  Allowed data type classes include:
145       *                        {@code Boolean}, {@code Date}, {@code Long}, and
146       *                        {@code String}.  It must not be {@code null}.
147       * @param  required       Indicates whether this property must be provided
148       *                        when scheduling a task.
149       * @param  multiValued    Indicates whether this property is allowed to have
150       *                        multiple values.
151       * @param  advanced       Indicates whether this property may be considered
152       *                        advanced and doesn't necessarily need to be
153       *                        presented to the user.  Advanced properties must not
154       *                        be required.
155       * @param  allowedValues  The set of allowed values for this task property.
156       *                        It may be {@code null} if there is not a predefined
157       *                        set of acceptable values.  If it is provided, then
158       *                        all values must be objects of the class specified as
159       *                        the data type.
160       */
161      public TaskProperty(final String attributeName, final String displayName,
162                          final String description, final Class<?> dataType,
163                          final boolean required, final boolean multiValued,
164                          final boolean advanced, final Object[] allowedValues)
165      {
166        ensureNotNull(attributeName, displayName, description, dataType);
167        ensureTrue(dataType.equals(Boolean.class) || dataType.equals(Date.class) ||
168                   dataType.equals(Long.class) || dataType.equals(String.class));
169        ensureFalse(required && advanced,
170                    "TaskProperty.required and advanced must not both be true.");
171    
172        this.attributeName = attributeName;
173        this.displayName   = displayName;
174        this.description   = description;
175        this.dataType      = dataType;
176        this.required      = required;
177        this.multiValued   = multiValued;
178        this.advanced      = advanced;
179    
180        if ((allowedValues == null) || (allowedValues.length == 0))
181        {
182          this.allowedValues = null;
183        }
184        else
185        {
186          for (final Object o : allowedValues)
187          {
188            ensureTrue(dataType.equals(o.getClass()));
189          }
190    
191          this.allowedValues = allowedValues;
192        }
193      }
194    
195    
196    
197      /**
198       * Retrieves the name of the LDAP attribute associated with this task
199       * property.
200       *
201       * @return  The name of the LDAP attribute associated with this task property.
202       */
203      public String getAttributeName()
204      {
205        return attributeName;
206      }
207    
208    
209    
210      /**
211       * Retrieves the human-readable display name for this task property.
212       *
213       * @return  The human-readable display name for this task property.
214       */
215      public String getDisplayName()
216      {
217        return displayName;
218      }
219    
220    
221    
222      /**
223       * Retrieves the human-readable description for this task property.
224       *
225       * @return  The human-readable description for this task property.
226       */
227      public String getDescription()
228      {
229        return description;
230      }
231    
232    
233    
234      /**
235       * Retrieves the data type for this task property, which represents the
236       * expected data type for the value(s) of this property.  Supported data types
237       * include {@code Boolean}, {@code Date}, {@code Long}, and {@code String}.
238       *
239       * @return  The data type for this task property.
240       */
241      public Class<?> getDataType()
242      {
243        return dataType;
244      }
245    
246    
247    
248      /**
249       * Indicates whether this task property is required to be provided in order to
250       * schedule a task.
251       *
252       * @return  {@code true} if this task property is required, or {@code false}
253       *          if it is not.
254       */
255      public boolean isRequired()
256      {
257        return required;
258      }
259    
260    
261    
262      /**
263       * Indicates whether this task property is allowed to have multiple values.
264       *
265       * @return  {@code true} if this task property is allowed to have multiple
266       *          values, or {@code false} if it may only have a single value.
267       */
268      public boolean isMultiValued()
269      {
270        return multiValued;
271      }
272    
273    
274    
275      /**
276       * Indicates whether this task property is considered advanced.  Advanced
277       * properties are not necessarily required to schedule the task and may be
278       * hidden from the user if simplicity is desired over flexibility.
279       *
280       * @return  {@code true} if this task property is considered advanced, or
281       *          {@code false} if not.
282       */
283      public boolean isAdvanced()
284      {
285        return advanced;
286      }
287    
288    
289    
290      /**
291       * Retrieves the set of values that may be used for this task property.
292       *
293       * @return  The set of values that may be used for this task property, or
294       *          {@code null} if there is not a predefined set of allowed values.
295       */
296      public Object[] getAllowedValues()
297      {
298        return allowedValues;
299      }
300    
301    
302    
303      /**
304       * Retrieves a string representation of this task property.
305       *
306       * @return  A string representation of this task property.
307       */
308      @Override()
309      public String toString()
310      {
311        final StringBuilder buffer = new StringBuilder();
312        toString(buffer);
313        return buffer.toString();
314      }
315    
316    
317    
318      /**
319       * Appends a string representation of this task property to the provided
320       * buffer.
321       *
322       * @param  buffer  The buffer to which the string representation should be
323       *                 appended.
324       */
325      public void toString(final StringBuilder buffer)
326      {
327        buffer.append("TaskProperty(attrName='");
328        buffer.append(attributeName);
329        buffer.append("', displayName='");
330        buffer.append(displayName);
331        buffer.append("', description='");
332        buffer.append(description);
333        buffer.append("', dataType='");
334        buffer.append(dataType.getName());
335        buffer.append("', required=");
336        buffer.append(required);
337        buffer.append("', multiValued=");
338        buffer.append(multiValued);
339        buffer.append("', advanced=");
340        buffer.append(advanced);
341    
342        if (allowedValues != null)
343        {
344          buffer.append(", allowedValues={");
345          for (int i=0; i < allowedValues.length; i++)
346          {
347            if (i > 0)
348            {
349              buffer.append(", ");
350            }
351    
352            buffer.append('\'');
353            buffer.append(allowedValues[i]);
354            buffer.append('\'');
355          }
356          buffer.append('}');
357        }
358    
359        buffer.append(')');
360      }
361    }