Interface IValueDescriptor<Value, Builder extends IValueBuilder<Value>>

Type Parameters:
Value - Type of the Java object representing the data.
Builder - Type of the builder for creating a new instance of the data type described by this descriptor.
All Superinterfaces:
IAttributeConfigurable<IValueDescriptor<Value,Builder>>, Serializable
All Known Subinterfaces:
IAnyValueDescriptor, IBooleanValueDescriptor, IConstValueDescriptor<V>, IFloatValueDescriptor, IIntegerValueDescriptor, ILargeStringValueDescriptor, IListValueDescriptor<V>, IMapValueDescriptor<V>, INullValueDescriptor, IRecordValueDescriptor, IStringValueDescriptor, ITupleValueDescriptor, IUnionValueDescriptor, IVoidValueDescriptor
All Known Implementing Classes:
AttachmentDescriptor, FileItemDescriptor, FormRecordChatDescriptor, FormRecordMessageDescriptor, FormRecordMessageUploadRequestDescriptor, MimeTypeDescriptor, RecordValueDescriptorWrapper, UserDataDescriptor, UserProfileDescriptor
public interface IValueDescriptor<Value, Builder extends IValueBuilder<Value>> extends IAttributeConfigurable<IValueDescriptor<Value,Builder>>, Serializable
Base class for all value descriptors that describe the shape of (mostly JSON-like) data. A value descriptor indicates the type a value must have and may impose additional restrictions on the allowed values. 

IValueBuilderFactory f = ValueBuilderFactory.getInstance();
IListValueDescriptor descriptor = f.listBuilder(f.string()).description("i18n.key").build();

// Obtain a list of available properties, to create an overview table etc.
List<IProperty> properties = descriptor.getKnownProperties("Root");

// Property[path=Root, type=List, description="i18n.key"]
System.out.println(properties.get(0));

// Property[path=Root[i], type=String, description="Root[i]"]
System.out.println(properties.get(1));

List<String> list = descriptor.builder().set(0, "foo").set(1, "bar").build();

// ["foo", "bar"]
System.out.println(list);
Since:
7.0.0
Author:
XIMA MEDIA GmbH

  • Method Details

    • acceptsValue

      default boolean acceptsValue(Object value)
      Tests whether the given value conforms to the restrictions imposed by this value descriptor.
      Parameters:
      value - A value to check.
      Returns:
      true when the given value conforms to the restrictions imposed by this value descriptor, false otherwise.

    • acceptsValue

      boolean acceptsValue(Object value, IValueAcceptanceCriteria criteria)
      Tests whether the given value conforms to the restrictions imposed by this value descriptor. Allows you to specify the acceptance criteria to check that control which restrictions are actually checked.
      Parameters:
      value - A value to check.
      Returns:
      true when the given value conforms to the restrictions imposed by this value descriptor, false otherwise.

    • asAny

      IAnyValueDescriptor asAny()
      Casts this descriptor to an any value descriptor type.
      Returns:
      This value descriptor cast to an any value descriptor.
      Throws:
      ClassCastException - When this descriptor cannot be cast to the desired type.

    • asBoolean

      IBooleanValueDescriptor asBoolean()
      Casts this descriptor to a boolean value descriptor type.
      Returns:
      This value descriptor cast to a boolean value descriptor.
      Throws:
      ClassCastException - When this descriptor cannot be cast to the desired type.

    • asConst

      <T> IConstValueDescriptor<T> asConst()
      Casts this descriptor to a constant value descriptor type.
      Type Parameters:
      T - Type of the constant.
      Returns:
      This value descriptor cast to a constant value descriptor.
      Throws:
      ClassCastException - When this descriptor cannot be cast to the desired type.

    • asFloat

      IFloatValueDescriptor asFloat()
      Casts this descriptor to a float value descriptor type.
      Returns:
      This value descriptor cast to a float value descriptor.
      Throws:
      ClassCastException - When this descriptor cannot be cast to the desired type.

    • asInteger

      IIntegerValueDescriptor asInteger()
      Casts this descriptor to an integer value descriptor type.
      Returns:
      This value descriptor cast to an integer value descriptor.
      Throws:
      ClassCastException - When this descriptor cannot be cast to the desired type.

    • asLargeString

      ILargeStringValueDescriptor asLargeString()
      Casts this descriptor to a large string value descriptor type.
      Returns:
      This value descriptor cast to a large string value descriptor.
      Throws:
      ClassCastException - When this descriptor cannot be cast to the desired type.

    • asList

      IListValueDescriptor<?> asList()
      Casts this descriptor to a list value descriptor type.
      Returns:
      This value descriptor cast to a list value descriptor.
      Throws:
      ClassCastException - When this descriptor cannot be cast to the desired type.

    • asList

      <S> IListValueDescriptor<S> asList(Class<S> elementType)
      Casts this descriptor to a list value descriptor type.
      Type Parameters:
      S - Type of the elements contained in the list.
      Parameters:
      elementType - Type of the elements contained in the list.
      Returns:
      This value descriptor cast to a list value descriptor.
      Throws:
      ClassCastException - When this descriptor cannot be cast to the desired type.

    • asMap

      IMapValueDescriptor<?> asMap()
      Casts this descriptor to a map value descriptor type.
      Returns:
      This value descriptor cast to a map value descriptor.
      Throws:
      ClassCastException - When this descriptor cannot be cast to the desired type.

    • asMap

      <S> IMapValueDescriptor<S> asMap(Class<S> valueType)
      Casts this descriptor to a map value descriptor type.
      Type Parameters:
      S - Type of the values contained in the map.
      Parameters:
      valueType - Type of the values contained in the map.
      Returns:
      This value descriptor cast to a map value descriptor.
      Throws:
      ClassCastException - When this descriptor cannot be cast to the desired type.

    • asNull

      INullValueDescriptor asNull()
      Casts this descriptor to a null value descriptor type.
      Returns:
      This value descriptor cast to a null value descriptor.
      Throws:
      ClassCastException - When this descriptor cannot be cast to the desired type.

    • asRecord

      IRecordValueDescriptor asRecord()
      Casts this descriptor to a record value descriptor type.
      Returns:
      This value descriptor cast to a record value descriptor.
      Throws:
      ClassCastException - When this descriptor cannot be cast to the desired type.

    • asString

      IStringValueDescriptor asString()
      Casts this descriptor to a string value descriptor type.
      Returns:
      This value descriptor cast to a string value descriptor.
      Throws:
      ClassCastException - When this descriptor cannot be cast to the desired type.

    • asTuple

      ITupleValueDescriptor asTuple()
      Casts this descriptor to a tuple value descriptor type.
      Returns:
      This value descriptor cast to a tuple value descriptor.
      Throws:
      ClassCastException - When this descriptor cannot be cast to the desired type.

    • asUnion

      IUnionValueDescriptor asUnion()
      Casts this descriptor to a union value descriptor type.
      Returns:
      This value descriptor cast to a union value descriptor.
      Throws:
      ClassCastException - When this descriptor cannot be cast to the desired type.

    • asUnion

      @Deprecated default IUnionValueDescriptor asUnion(Class<?> type)
      Deprecated.
      Use asUnion() instead. There is no discriminator anymore.
      Casts this descriptor to a union value descriptor type with a discriminator of the given type.
      Parameters:
      type - Type of the union discriminator.
      Returns:
      This value descriptor cast to a union value descriptor.
      Throws:
      ClassCastException - When this descriptor cannot be cast to the desired type.

    • asVoid

      default IVoidValueDescriptor asVoid()
      Casts this descriptor to a void value descriptor type.
      Returns:
      This value descriptor cast to a void value descriptor.
      Throws:
      ClassCastException - When this descriptor cannot be cast to the desired type.

    • builder

      Builder builder()
      Creates a new value builder for creating a value that conforms to the restrictions imposed by this value descriptor. This behaves identically to builder(defaults), i.e. using the default configuration for the builder. See IValueBuilderConfigurator for details on the default values for each configuration option.
      Returns:
      A new value builder for values as indicated by this value descriptor.
      See Also:

    • builder

      Builder builder(IValueBuilderOptions options)
      Creates a new value builder for creating a value that conforms to the restrictions imposed by this value descriptor. Allows you to specify options that control how the builder behaves.
      Returns:
      A new value builder for values as indicated by this value descriptor.
      See Also:

    • configure

      IValueDescriptorBuilder<Value,Builder,?> configure()
      Creates a new builder pre-configured with the settings of this descriptor. Lets you e.g. add additional properties.
      Returns:
      A new builder pre-configured with the settings of this descriptor.

    • getAttributes

      Map<String,Object> getAttributes()
      Gets a map of additional custom attributes associated with this value descriptor. The exact meaning of these attributes is up to the user of the value descriptor API.

      See StandardValueDescriptorAttributes for some standard attribute keys.

      Specified by:
      getAttributes in interface IAttributeConfigurable<Value>
      Returns:
      A map of additional attributes associated with this value descriptor.
      Since:
      8.5.0
      See Also:

    • getBaseType

      EValueType getBaseType()
      Gets the basic type of the value described by this value descriptor.
      Returns:
      The value's basic type.

    • getDefaultValue

      Value getDefaultValue()
      Gets the default value used if no explicit is provided when a value for this descriptor is created.
      Returns:
      The default value.

    • getDescription

      String getDescription()
      Deprecated.
      Use getStringAttribute(key) with the key VALUE_DESCRIPTOR_ATTR_DESCRIPTION.
      Gets the description for this value. This is passed through as set when the descriptor was created. Could be e.g. a localized message or a message key. The exact interpretation is up to the user of the value descriptor API.
      Returns:
      Description for this value.

    • getFullType

      String getFullType()
      Gets a string containing the full value type of this value descriptors, including the type of list elements or map values. For example, if this descriptor describes a list of strings, this method returns List<string>.
      Returns:
      The value's full type.

    • getFullTypeWithRestrictions

      String getFullTypeWithRestrictions()
      Gets a string containing the full value type of this value descriptors, including the type of list elements or map values, as well as any restrictions imposed by this descriptor. For example, if this descriptor describes a list of strings with at least one element, this method returns List<string>(length=[1,∞).
      Returns:
      The value's full type with restrictions.

    • getJavaClass

      Class<? extends Value> getJavaClass()
      Gets the Java class of the values described by this descriptor.
      Returns:
      The value's Java class.

    • getKnownProperties

      @Deprecated default List<IProperty> getKnownProperties(String basePath)
      Deprecated.
      Use ValueDescriptorPropertyExtractor
      Gets a list of all properties known to exist when a value of this type is created. For example, if a record has required properties, these properties are included in the returned list.
      Parameters:
      basePath - Prefix added to the property paths.
      Returns:
      A list of all properties known to exist when a value of this type is created.

    • getKnownProperties

      @Deprecated default List<IProperty> getKnownProperties(String jsonPath, String basePath, int nestingLevel)
      Deprecated.
      Use ValueDescriptorPropertyExtractor
      Gets a list of all properties known to exist when a value of this type is created. For example, if a record has required properties, these properties are included in the returned list.
      Parameters:
      jsonPath - The current JSON path ("$" for root, "$.property" for a property, etc.).
      basePath - Prefix added to the property paths.
      nestingLevel - The current nesting level (0 for root, 1 for first level children, etc.).
      Returns:
      A list of all properties known to exist when a value of this type is created.

    • intersect

      IValueDescriptor<?,?> intersect(IValueDescriptor<?,?> other)
      Intersects this value descriptor with the given type. This is a shortcut for using the default factory, see IValueDescriptorFactory#intersect for details.
      Parameters:
      other - Another value descriptor.
      Returns:
      The intersection of this and the given value descriptor.
      Since:
      8.1.0

    • is

      boolean is(Class<? extends IValueDescriptor> clazz)
      Checks whether this descriptor can be cast to the given class. Use this method to check before calling unwrap().
      Parameters:
      clazz - Class to check.
      Returns:
      Whether this descriptor can be cast to the given class.
      See Also:

    • match

      <R> R match(IValueDescriptorTypeMatcher<R> matcher, R defaultValue)
      Matches this type of value descriptor using the given matcher, calling the matcher method corresponding to the actual type of this descriptor.
      Type Parameters:
      R - The return type of the matcher.
      Parameters:
      matcher - The matcher to use.
      defaultValue - The default value to return if the matcher does not handle this type.
      Returns:
      The result of the matcher.

    • unwrap

      <TItem, TDesc extends IValueDescriptor<TItem, ? extends IValueBuilder<TItem>>> TDesc unwrap(Class<? extends TDesc> clazz)
      Casts this descriptor to the given type. Make sure you are certain it is of the given type.
      Type Parameters:
      TItem - Type of the values described by the descriptor.
      TDesc - Type of the descriptor.
      Parameters:
      clazz - Class to which to cast this descriptor.
      Returns:
      This value descriptor cast to the given type.
      Throws:
      ClassCastException - When this descriptor cannot be cast to the given type.
      See Also:

    • withDefaultValue

      IValueDescriptor<Value,Builder> withDefaultValue(Object defaultValue)
      Gets a new value descriptor with the default value changed to the given value.
      Parameters:
      defaultValue - The new default value. May be changed when it does not conform to the restrictions imposed by this descriptor.
      Returns:
      A new descriptor with the default value.
      Since:
      8.1.0

    • withDescription

      IValueDescriptor<Value,Builder> withDescription(String description)
      Deprecated.
      Use withAttribute(key, value) with the key VALUE_DESCRIPTOR_ATTR_DESCRIPTION instead.
      Gets a new value descriptor with the description changed to the given description.
      Parameters:
      description - The new description.
      Returns:
      A new descriptor with the given description.
      Since:
      8.1.0