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