PropertyDescriptor

/*
 * Copyright 2012-2013 smartics, Kronseder & Reiner GmbH
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package de.smartics.properties.api.core.domain;

import java.io.Serializable;
import java.util.List;
import java.util.Locale;

import de.smartics.properties.api.core.annotations.AccessType;
import de.smartics.properties.api.core.annotations.PropertyDefinitionTime;
import de.smartics.properties.api.core.annotations.PropertyUse.UseType;

/**
 * Defines property meta data. This information excludes the actual property
 * value. It provides information such as name, type, default values and
 * constraints on the property value.
 */
public interface PropertyDescriptor extends Serializable
{
  // ********************************* Fields *********************************

  // --- constants ------------------------------------------------------------

  // ****************************** Initializer *******************************

  // ****************************** Inner Classes *****************************

  // ********************************* Methods ********************************

  // --- get&set --------------------------------------------------------------

  /**
   * Returns the context of the property descriptor.
   *
   * @return the context of the property descriptor.
   */
  PropertyContext getContext();

  /**
   * Returns the type that declares the property that is described by this
   * instance.
   *
   * @return the declaring type of the property this instance is the descriptor
   *         for.
   */
  Class<?> getDeclaringType();

  /**
   * Returns the key of the property.
   * <p>
   * This value must not be <code>null</code>.
   * </p>
   *
   * @return the name of the component the property belongs to.
   */
  PropertyKey getKey();

  /**
   * Returns the type of the property value.
   * <p>
   * This value must not be <code>null</code>.
   * </p>
   * <p>
   * If there is no value range specified for the property type, the type is
   * either required to specify a static fromString method or is a standard or
   * registered type whose conversion rules are well known.
   * </p>
   *
   * <pre>
   * public static T fromString(String value);
   * </pre>
   *
   * @return the type of the property value.
   */
  PropertyType getType();

  /**
   * Checks if the property is mandatory to be not <code>null</code>. If the
   * property is not mandatory, it is optional.
   *
   * @return <code>true</code> if the property is mandatory to be not
   *         <code>null</code>, <code>false</code> otherwise.
   */
  boolean isMandatory();

  /**
   * Checks if the property is secured.
   *
   * @return <code>true</code> if the property is secured, <code>false</code> if
   *         is readable by anyone.
   */
  boolean isSecured();

  /**
   * Returns the flag to define the access type.
   *
   * @return the flag to define the access type.
   */
  AccessType getAccessType();

  /**
   * Checks whether or not the property is mutable at runtime.
   *
   * @return <code>true</code> if the property may be changed after startup,
   *         <code>false</code> if the property value is immutable (that is:
   *         stays the same) after startup.
   * @see #getUpdateIntervalInMs()
   */
  boolean isRuntimeMutable();

  /**
   * Returns the update interval in milliseconds (ms).
   * <p>
   * An application may cache the value of the property for the given period of
   * time.
   * </p>
   *
   * <pre>
   * {@table [nofill]
   *   || value | description ||
   *   || &lt; 0 | Property is not mutable. ||
   *   || 0      | Property is read on each access. ||
   *   || &gt; 0 | Property is required to be read new after the given number
   *               of ms elapsed. In the meantime a previously read cached value
   *               is returned.||
   * }
   * </pre>
   * <p>
   * The constants defined in
   * {@link de.smartics.properties.api.core.annotations.PropertyLifecycle.UpdateInterval}
   * provide constants to define intervals.
   * </p>
   *
   * @return the update interval in milliseconds (ms).
   */
  long getUpdateIntervalInMs();

  // TODO: Discussion: Maybe we should allow an expression here that would
  // a) make the time more readable (e.g. "5min")
  // b) allow to reference other properties (e.g. "${my.defaultTime}")
  // The problem is that
  // a) The syntax may be more confusing (e.g. "5 minutes" will not be parsed)
  // and could be made more clear by Java constants.
  // b) the name of the referenced property is given as a
  // String. Refactoring the name property of the property in the interface will
  // not affect the property name here.

  /**
   * The designed time the property is defined.
   * <p>
   * This value must not be <code>null</code>.
   * </p>
   *
   * @return the designed time the property is defined.
   */
  PropertyDefinitionTime getConfigurationTime();

  /**
   * Returns the expression to use to construct the value of the property. An
   * expression may reference another property or may serve as a template
   * containing any number of property references.
   * <p>
   * Resolving fails if at least one property reference cannot be resolved.
   * </p>
   * {@example $ server}/path/${command}}
   *
   * @return the value of the expression. May be <code>null</code>.
   */
  PropertyExpression getDefaultExpression();

  /**
   * Returns the range of values allowed for this property.
   * <p>
   * The returned value may be <code>null</code> if there is no specific range
   * of values the value of the property has to be part of. For instance a
   * property may have no value range or only value ranges that are not
   * enumerable. The latter may only be modeled by a property constraint.
   * </p>
   *
   * @return the range for values allowed for this property. May be
   *         <code>null</code>.
   */
  PropertyValueRange<?> getValueRange();

  /**
   * Returns a list of constraints a value for the property has to meet.
   *
   * @return a list of constraints a value for the property has to meet. The
   *         list may be empty, but is never <code>null</code>.
   */
  List<? extends PropertyConstraint<?>> getConstraints();

  /**
   * Returns the name of the document that identifies the document uniquely
   * within the context of the project. It is used to select the projectdoc
   * document in the <code>META-INF</code> folder.
   *
   * @return the name of the document that identifies the document uniquely
   *         within the context of the project.
   */
  DocumentName getDocumentName();

  /**
   * Returns the meta data information for the property.
   * <p>
   * This value must not be <code>null</code>.
   * </p>
   *
   * @return the meta data information for the property.
   */
  PropertyProjectdoc getDocumentMetaData();

  /**
   * Returns the meta data information for the property.
   * <p>
   * This value must not be <code>null</code>.
   * </p>
   *
   * @param locale the locale to determine which bundle to use.
   * @return the meta data information for the property.
   */
  PropertyProjectdoc getDocumentMetaData(Locale locale);

  /**
   * Returns the meta data information for the property set.
   * <p>
   * This value must not be <code>null</code>.
   * </p>
   *
   * @return the meta data information for the property set.
   */
  PropertySetProjectdoc getDocumentMetaDataProjectSet();

  /**
   * Returns the meta data information for the property set.
   * <p>
   * This value must not be <code>null</code>.
   * </p>
   *
   * @param locale the locale to determine which bundle to use.
   * @return the meta data information for the property set.
   */
  PropertySetProjectdoc getDocumentMetaDataProjectSet(Locale locale);

  /**
   * Returns the comment to the property and its values.
   * <p>
   * This value must not be <code>null</code>.
   * </p>
   *
   * @return the comment to the property and its values.
   */
  PropertyComment getComment();

  /**
   * Returns the comment to the property and its values.
   * <p>
   * This value must not be <code>null</code>.
   * </p>
   *
   * @param locale the locale to determine which bundle to use.
   * @return the comment to the property and its values.
   */
  PropertyComment getComment(Locale locale);

  /**
   * Returns the categories this property is associated with.
   *
   * @return the categories this property is associated with.
   */
  PropertyCategories getCategories();

  /**
   * Returns the use type of the property.
   *
   * @return the use type of the property.
   */
  UseType getUseType();

  // --- business -------------------------------------------------------------

  // --- object basics --------------------------------------------------------

}