Class ImplementationHelper

java.lang.Object
org.apache.sis.util.Static
org.apache.sis.internal.metadata.ImplementationHelper

public final class ImplementationHelper extends Static
Miscellaneous utility methods for implementation of metadata classes. Many methods in this class are related to (un)marshalling. This is not an helper class for usage of metadata.
Since:
0.3
Version:
1.3
  • Field Details

    • ISO_NAMESPACE

      public static final String ISO_NAMESPACE
      The root directory of ISO namespaces. Value is "http://standards.iso.org/iso/".
      See Also:
  • Constructor Details

    • ImplementationHelper

      private ImplementationHelper()
      Do not allow instantiation of this class.
  • Method Details

    • toMilliseconds

      public static long toMilliseconds(Date value)
      Returns the milliseconds value of the given date, or Long.MIN_VALUE if the date us null.
      Parameters:
      value - the date, or null.
      Returns:
      the time in milliseconds, or Long.MIN_VALUE if none.
    • toDate

      public static Date toDate(long value)
      Converts the given milliseconds time to a date object, or returns null if the given time is Long.MIN_VALUE.
      Parameters:
      value - the time in milliseconds.
      Returns:
      the date for the given milliseconds value, or null.
    • valueIfDefined

      public static Collection<?> valueIfDefined(Collection<?> value)
      Returns the given collection if non-null and non-empty, or null otherwise. This method is used for calls to checkWritePermission(Object).
      Parameters:
      value - the collection.
      Returns:
      the given collection if non-empty, or null otherwise.
    • ensurePositive

      public static boolean ensurePositive(Class<?> classe, String property, boolean strict, Number newValue) throws IllegalArgumentException
      Ensures that the given property value is positive. If the user gave a negative value or (in some case) zero, then this method logs a warning if we are in process of (un)marshalling a XML document or throw an exception otherwise.
      Parameters:
      classe - the class which invoke this method.
      property - the property name. Method name will be inferred by the usual Java bean convention.
      strict - true if the value was expected to be strictly positive, or false if 0 is accepted.
      newValue - the argument value to verify.
      Returns:
      true if the value is valid.
      Throws:
      IllegalArgumentException - if the given value is negative and the problem has not been logged.
    • ensureInRange

      public static boolean ensureInRange(Class<?> classe, String property, Number minimum, Number maximum, Number newValue) throws IllegalArgumentException
      Ensures that the given argument is either null or between the given minimum and maximum values. If the user argument is outside the expected range of values, then this method logs a warning if we are in process of (un)marshalling a XML document or throw an exception otherwise.
      Parameters:
      classe - the class which invoke this method.
      property - name of the property to check.
      minimum - the minimal legal value.
      maximum - the maximal legal value.
      newValue - the value given by the user.
      Returns:
      true if the value is valid.
      Throws:
      IllegalArgumentException - if the given value is out of range and the problem has not been logged.
    • logOrFormat

      private static String logOrFormat(Class<?> classe, String property, short key, Object... arguments)
      Formats an error message and logs it if we are (un)marshalling a document, or return the message otherwise. In the latter case, it is caller's responsibility to use the message for throwing an exception.
      Parameters:
      classe - the caller class, used only in case of warning message to log.
      property - the property name. Method name will be inferred by the usual Java bean convention.
      key - an Errors.Keys value.
      arguments - the argument to use for formatting the error message.
      Returns:
      null if the message has been logged, or the message to put in an exception otherwise.
    • propertyAlreadySet

      public static void propertyAlreadySet(Class<?> classe, String method, String name) throws IllegalStateException
      Invoked by private setter methods (themselves invoked by JAXB at unmarshalling time) when an element is already set. Invoking this method from those setter methods serves three purposes:
      • Make sure that a singleton property is not defined twice in the XML document.
      • Protect ourselves against changes in immutable objects outside unmarshalling. It should not be necessary since the setter methods shall not be public, but we are paranoiac.
      • Be a central point where we can trace all setter methods, in case we want to improve warning or error messages in future SIS versions.
      Parameters:
      classe - the caller class, used only in case of warning message to log.
      method - the caller method, used only in case of warning message to log.
      name - the property name, used only in case of error message to format.
      Throws:
      IllegalStateException - if isDefined is true and we are not unmarshalling an object.
      Since:
      0.7
    • setFirst

      public static <T> Collection<T> setFirst(Collection<T> values, T newValue)
      Sets the first element in the given collection to the given value. Special cases:
      • If the given collection is null, a new collection will be returned.
      • If the given new value is null, then the first element in the collection is removed.
      • Otherwise if the given collection is empty, the given value will be added to it.
      Type Parameters:
      T - the type of elements in the collection.
      Parameters:
      values - the collection where to add the new value, or null.
      newValue - the new value to set, or null for instead removing the first element.
      Returns:
      the collection (may or may not be the given values collection).
      See Also:
    • getObjectID

      public static String getObjectID(IdentifiedObject object)
      Returns the gco:id or gml:id value to use for the given object. The returned identifier will be unique in the current XML document.
      Parameters:
      object - the object for which to get the unique identifier.
      Returns:
      the unique XML identifier, or null if none.
      Since:
      0.7
    • setObjectID

      public static void setObjectID(IdentifiedObject object, String id)
      Invoked by setID(String) method implementations for assigning an identifier to an object at unmarshalling time.
      Parameters:
      object - the object for which to assign an identifier.
      id - the gco:id or gml:id value.
      Since:
      0.7