001/*
002 * JPPF.
003 * Copyright (C) 2005-2018 JPPF Team.
004 * http://www.jppf.org
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * You may obtain a copy of the License at
009 *
010 *   http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018
019package org.jppf.utils.configuration;
020
021import java.io.Serializable;
022import java.util.*;
023
024/**
025 * Interface for predefined JPPF properties expected to handle a specific value type.
026 * @param <T> the type of the value of this property.
027 * @author Laurent Cohen
028 * @since 5.2
029 */
030public interface JPPFProperty<T> extends Serializable {
031  /**
032   * Get the name of this property.
033   * @return the property's name.
034   */
035  String getName();
036
037  /**
038   * Get the default value of this property.
039   * @return the default value;
040   */
041  T getDefaultValue();
042
043  /**
044   * Get the aliases for this property, that is, other names it may be known as such as legacy names from prior versions.
045   * @return an array of the aliases for this property, possibly empty.
046   */
047  String[] getAliases();
048
049  /**
050   * Convert the specified value into the type of values handled by this property.
051   * @param value the property value to convert.
052   * @return the value converted to the type of this property.
053   */
054  T valueOf(String value);
055
056  /**
057   * Convert the specified value to a string.
058   * @param value the property value to convert.
059   * @return a String representation of the value.
060   */
061  String toString(final T value);
062
063  /**
064   * Return the class object for the type of values of this property.
065   * @return a {@link Class} instance.
066   */
067  Class<T> valueType();
068
069  /**
070   * Get a short label for this property.
071   * @return the label as a string.
072   */
073  String getShortLabel();
074
075  /**
076   * Get a short label for this property.
077   * @param locale the locale in which the short label of this property should be returned.
078   * @return the label as a string.
079   */
080  String getShortLabel(Locale locale);
081
082  /**
083   * Get a description of this property.
084   * @param locale the locale in which the documentation of this property should be returned.
085   * @return the description as a string.
086   */
087  String getDocumentation(Locale locale);
088
089  /**
090   * Get a description of this property.
091   * @return the description as a string.
092   */
093  String getDocumentation();
094
095  /**
096   * Get the set of tags that apply to this property.
097   * @return a set of tags as strings.
098   */
099  Set<String> getTags();
100
101  /**
102   * Get the parmaeters specified in the name of property, if any.
103   * Parameters are specified as in this example: {@code my.<param1>.property.<param2>.name = some value}.
104   * @return an array of the parameter names, empty if there is no parameter.
105   * @since 6.0
106   */
107  String[] getParameters();
108
109  /**
110   * Get the documeentation for the specified parmaeter, if it exists.
111   * @param param the name of the parameter for which to find a description.
112   * @return a string describing the parameter.
113   * @since 6.0
114   */
115  String getParameterDoc(String param);
116
117  /**
118   * Get a string explaining why a property was deprecated and/or what to use instead.
119   * @return a text documentation about this property's deprecation.
120   */
121  String getDeprecatedDoc();
122
123  /**
124   * Get a string explaining why a property was deprecated and/or what to use instead.
125   * @param locale the locale in which the text should be returned.
126   * @return a text documentation about this property's deprecation.
127   */
128  public String getDeprecatedDoc(Locale locale);
129
130  /**
131   * Resolve the name of the property by substituting the parameters names with actual values.
132   * @param params the values of the parameters.
133   * @return the new resolve name.
134   * @since 6.0
135   * @exclude
136   */
137  public String resolveName(String...params);
138
139  /**
140   * Resolve the specified alias for the property's name by substituting the parameters names with actual values.
141   * @param alias the alias to resolve.
142   * @param params the values of the parameters.
143   * @return the new resolve name.
144   * @since 6.0
145   * @exclude
146   */
147  public String resolveName(String alias, String...params);
148
149  /**
150   * Determine whether this property is deprecated.
151   * @return {@code true} if the property is deprecated, {@code false} otherwise.
152   */
153  boolean isDeprecated();
154
155  /**
156   * Specify whether this property is deprecated.
157   * @param deprecated {@code true} if the property is deprecated, {@code false} otherwise.
158   * @return this property, for method call chaining.
159   * @exclude
160   */
161  JPPFProperty<T> setDeprecated(boolean deprecated);
162}