com.isomorphic.datasource

## Class DSField

- java.lang.Object
- - org.apache.commons.collections4.map.AbstractIterableMap
  - - com.isomorphic.collections.DataTypeMap
    - - com.isomorphic.datasource.DSField

- All Implemented Interfaces:
    java.util.Map, org.apache.commons.collections4.Get, org.apache.commons.collections4.IterableGet, org.apache.commons.collections4.IterableMap, org.apache.commons.collections4.Put

      public class DSField
      extends DataTypeMap

  Server-side representation of a DataSource Field.

  Contains accessors for all documented DataSource properties and a general getProperty() API for retrieving your own properties for custom DataSource implementations.

- - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.String` | `getBeanPropertyName()` Returns property name for this field: Returns `valueXPath` if specified.
    `java.lang.String` | `getForeignKey()` Returns the foreign key, if set.
    `java.lang.String` | `getIncludeFrom()` Returns value for "includeFrom" property of this field if set, `null` otherwise
    `java.lang.String` | `getJoinDSName()` For a `many-to-many` Relation Field only, returns the name of the join DataSource - ie the third dataSource "in the middle" of the relationship.
    `java.lang.Long` | `getLength()` Returns the length of this field, if specified.
    `java.util.List` | `getListProperty(java.lang.String property)` Returns the value of the specified attribute as a List.
    `java.util.Map` | `getMapProperty(java.lang.String property)` Returns the value of the specified attribute as a Map.
    `java.lang.String` | `getName()` Returns the name of this field.
    `java.lang.String` | `getNativeName()` Returns the native name of this field.
    `java.lang.Object` | `getObjectProperty(java.lang.String property)` Returns the value of the specified element(s) as an Object. Custom XML is transformed to Strings or Java collections by the following rules: Elements with just text (no child elements or attributes) become Strings Elements with child elements or attributes become Maps containing data derived from their subelements Repeating elements (more than one of the same name at the same level) become Lists Sample XML: Map `<field> <mapCustomProperty key1="value1" key2="value2" /> </field>` List of String `<field> <listCustomProperty>ListElement1</listCustomProperty> <listCustomProperty>ListElement2</listCustomProperty> </field>` List of Map `<field> <mapCustomProperty key1="value1" key2="value2" /> <mapCustomProperty key1="value1" key2="value2" /> </field>`
    `java.lang.String` | `getOtherFKs()` Returns `otherFKs` property, if set.
    `java.lang.String` | `getProperty(java.lang.String property)` For an XML DataSource, returns the value of the specified attribute as a string.
    `java.lang.String` | `getRelatedDSName()` For a `one-to-many` or `many-to-many` Relation Field, returns the name of the related DataSource.
    `java.lang.String` | `getTitle()` Returns the title of this field, if any.
    `java.lang.String` | `getTitle(java.util.Locale locale)` Returns the i18n message for the localized field title, otherwise returns `String` title, if any.
    `java.lang.String` | `getTitleKey()` Returns the i18n key for the field title if it is localized, otherwise returns `null`.
    `java.lang.String` | `getType()` Returns the type of this field.
    `java.util.List` | `getValidators()` Returns the List of Validators defined on this DSField
    `java.lang.String` | `getValueWriteXPath()` For an XML DataSource, returns the XPath expression used as alternative way to set the field value.
    `java.lang.String` | `getValueXPath()` For an XML DataSource, returns the XPath expression used to retrieve the field value.
    `boolean` | `is1ManyRelation()` Returns true if this field is a one-to-many Relation Field - ie, a field that declares multiple:true and a foreignKey relationship to a "child" dataSource.
    `boolean` | `isAutoGenerated()` Returns true if this field value is auto-generated by data base or ORM provider, false otherwise.
    `boolean` | `isCalculated()` Returns true if this field value is calculated via "customSQLExpression", "template", "formula" or "valueOperation" attributes, false otherwise.
    `boolean` | `isConditionallyRequired()` Returns true if this field might be required.
    `boolean` | `isInapplicable()` Returns the value of this field's "inapplicable" property (default false)
    `boolean` | `isManyManyRelation()` Returns true if this field is a many-to-many Relation Field - ie, a field that declares multiple:true and a foreignKey relationship to a related dataSource, via a third "join" dataSource.
    `boolean` | `isPrimaryKey()` Returns true if this field is a primary key, false otherwise.
    `boolean` | `isRelation()` Returns true if this field is either a `one-to-many` or `many-to-many` Relation Field
    `boolean` | `isRequired()` Returns true if this field is required, false otherwise.
    `boolean` | `shouldEncodeInResponse()` Returns true if this is a field of binary type that also has "encodeInResponse" set

- - ### Method Detail

    - #### is1ManyRelation

          public boolean is1ManyRelation()

      Returns true if this field is a one-to-many Relation Field - ie, a field that declares multiple:true and a foreignKey relationship to a "child" dataSource. See the "Relations" article in the client documentation for more details
      Returns:
        true if this field is a one-to-many relation field, otherwise false

    - #### isManyManyRelation

          public boolean isManyManyRelation()

      Returns true if this field is a many-to-many Relation Field - ie, a field that declares multiple:true and a foreignKey relationship to a related dataSource, via a third "join" dataSource. See the "Relations" article in the client documentation for more details
      Returns:
        true if this field is a many-to-many relation field, otherwise false

    - #### isRelation

          public boolean isRelation()

      Returns true if this field is either a `one-to-many` or `many-to-many` Relation Field
      Returns:
        true if this field is either a one-to-many or many-to-many relation field, otherwise false

    - #### getRelatedDSName

          public java.lang.String getRelatedDSName()

      For a `one-to-many` or `many-to-many` Relation Field, returns the name of the related DataSource. See the "Relations" article in the client documentation for more details
      Returns:
        The name of the related DataSource if this field is a one-to-many or many-to-many relation field, otherwise null

    - #### getJoinDSName

          public java.lang.String getJoinDSName()

      For a `many-to-many` Relation Field only, returns the name of the join DataSource - ie the third dataSource "in the middle" of the relationship. See the "Relations" article in the client documentation for more details
      Returns:
        The name of the join DataSource if this field is a many-to-many relation field, otherwise null

    - #### getName

          public java.lang.String getName()

      Returns the name of this field.
      Returns:
        the name of this field

    - #### isRequired

          public boolean isRequired()

      Returns true if this field is required, false otherwise.
      Returns:
        true if this field is required, false otherwise

    - #### isConditionallyRequired

          public boolean isConditionallyRequired()

      Returns true if this field might be required. This causes the system to look for and run a "requires" validator on this field, rather than just looking at the "required" flag
      Returns:
        true if this field is required, false otherwise

    - #### getType

          public java.lang.String getType()

      Returns the type of this field.

      Valid values include (please see the client-side documentation for details of what these types mean):

      - text
      - boolean
      - integer
      - float
      - date
      - datetime
      - time
      - enum
      - intEnum
      - sequence
      - link
      - image
      - binary
      - imageFile
      - password
      - modifier
      - modifierTimestamp
      - creator
      - creatorTimestamp
      Note that user-defined types are also possible. Please see the client-side documentation for the SimpleType class.
      Returns:
        the type of this field

    - #### getLength

          public java.lang.Long getLength()

      Returns the length of this field, if specified.
      Returns:
        the length of this field, if specified

    - #### getTitle

          public java.lang.String getTitle()

      Returns the title of this field, if any. Note that if field title is localized, the i18n message for the field title will be returned.
      Returns:
        the title of this field, if any

    - #### getTitle

          public java.lang.String getTitle(java.util.Locale locale)

      Returns the i18n message for the localized field title, otherwise returns `String` title, if any.
      Parameters:
        `locale` - `java.util.Locale` to use. If `null` is passed default locale will be used.
      Returns:
        i18n message for the localized field title, otherwise `String` title, if any.

    - #### getTitleKey

          public java.lang.String getTitleKey()

      Returns the i18n key for the field title if it is localized, otherwise returns `null`.
      Returns:
        i18 key for the field title if any or `null` otherwise

    - #### isPrimaryKey

          public boolean isPrimaryKey()

      Returns true if this field is a primary key, false otherwise.
      Returns:
        true if this field is a primary key, false otherwise

    - #### isAutoGenerated

          public boolean isAutoGenerated()

      Returns true if this field value is auto-generated by data base or ORM provider, false otherwise. Field is auto-generated if either field type is "sequence" or "autoGenerated" property is set to true.
      Returns:
        true if this field is auto-generated, false otherwise

    - #### getForeignKey

          public java.lang.String getForeignKey()

      Returns the foreign key, if set.

      If set, declares that this field holds values that can be matched to values from another DataSource field, to create a relationship between records from different DataSources or even records within the same DataSource.

      The format of the foreign key is `<dataSourceId>.<fieldName>`.

      Returns:
        the foreign key, if set

    - #### getOtherFKs

          public java.lang.String getOtherFKs()

      Returns `otherFKs` property, if set.

      In addition to regular `foreign key` this property defines additional foreign keys if field is related to multiple DataSources. This property may include the FK defined in "foreignKey" property as well.

      The format of the otherFKs is coma separated foreign key sets, for example: `<firstDS>.<fieldName>,<secondDS>.<fieldName>`.

      Note that this property works only as an addition to regular FK, i.e. if `foreignKey` is not set, then foreign keys in `otherFK` will be completely ignored.

      Returns:
        coma separated foreign keys, if set

    - #### getNativeName

          public java.lang.String getNativeName()

      Returns the native name of this field.
      Returns:
        the native name of this field

    - #### getValueXPath

          public java.lang.String getValueXPath()

      For an XML DataSource, returns the XPath expression used to retrieve the field value. This expression will be evaluated relative to the record element.
      Returns:
        the XPath expression

    - #### getValueWriteXPath

          public java.lang.String getValueWriteXPath()

      For an XML DataSource, returns the XPath expression used as alternative way to set the field value. This expression will be evaluated relative to the record element.
      Returns:
        the XPath expression

    - #### isCalculated

          public boolean isCalculated()

      Returns true if this field value is calculated via "customSQLExpression", "template", "formula" or "valueOperation" attributes, false otherwise.
      Returns:
        true if this is calculated field, false otherwise

    - #### getProperty

          public java.lang.String getProperty(java.lang.String property)

      For an XML DataSource, returns the value of the specified attribute as a string.
      Parameters:
        `property` - the name of the attribute
      Returns:
        the value of the specified attribute as a string

    - #### getObjectProperty

          public java.lang.Object getObjectProperty(java.lang.String property)

      Returns the value of the specified element(s) as an Object.

      Custom XML is transformed to Strings or Java collections by the following rules:
      - Elements with just text (no child elements or attributes) become Strings
      - Elements with child elements or attributes become Maps containing data derived from their subelements
      - Repeating elements (more than one of the same name at the same level) become Lists

      Sample XML:

      - Map

        `<field>
        <mapCustomProperty key1="value1" key2="value2" />
        </field>`
      - List of String

        `<field>
        <listCustomProperty>ListElement1</listCustomProperty>
        <listCustomProperty>ListElement2</listCustomProperty> </field>`
      - List of Map

        `<field>
        <mapCustomProperty key1="value1" key2="value2" />
        <mapCustomProperty key1="value1" key2="value2" />
        </field>`

      Parameters:
        `property` - the name of the element(s)
      Returns:
        the value of the specified element(s) as an Object
      See Also:
        `DSField.getProperty(String)`, `DSField.getListProperty(String)`, `DSField.getMapProperty(String)`

    - #### getListProperty

          public java.util.List getListProperty(java.lang.String property)

      Returns the value of the specified attribute as a List.
      Parameters:
        `property` - the name of the attribute
      Returns:
        the value of the specified attribute as a List
      Throws:
        `java.lang.ClassCastException` - if requested property is not instanceof List
      See Also:
        `DSField.getProperty(String)`, `DSField.getObjectProperty(String)`, `DSField.getMapProperty(String)`

    - #### getMapProperty

          public java.util.Map getMapProperty(java.lang.String property)

      Returns the value of the specified attribute as a Map.
      Parameters:
        `property` - the name of the attribute
      Returns:
        the value of the specified attribute as a Map
      Throws:
        `java.lang.ClassCastException` - if requested property is not instanceof Map
      See Also:
        `DSField.getProperty(String)`, `DSField.getObjectProperty(String)`, `DSField.getListProperty(String)`

    - #### getValidators

          public java.util.List getValidators()

      Returns the List of Validators defined on this DSField
      Returns:
        the List of Validators defined on this DSField

    - #### getIncludeFrom

          public java.lang.String getIncludeFrom()

      Returns value for "includeFrom" property of this field if set, `null` otherwise

    - #### getBeanPropertyName

          public java.lang.String getBeanPropertyName()

      Returns property name for this field:
      - Returns `valueXPath` if specified. Supports only simple XPath definitions: "property/subProperty/subSubProperty". If XPath starts with slash ('/') - it is trimmed. Replaces slashes ('/') with periods ('.').
      - For simple properties property name matches field name.
      Returns:
        `String` bean property name. Can be composed of subproperties (for example: "address.zipCode").

    - #### shouldEncodeInResponse

          public boolean shouldEncodeInResponse()

      Returns true if this is a field of binary type that also has "encodeInResponse" set

    - #### isInapplicable

          public boolean isInapplicable()

      Returns the value of this field's "inapplicable" property (default false)