public interface

ElementCreator

implements MetadataCreator
com.google.gdata.model.ElementCreator

Class Overview

An element creator allows setting element information, which includes the following pieces:

  • name: The qualified name to use for input and output. Defaults to using the value in the ElementKey associated with the metadata. Setting the name here will override the default.
  • required: Validates that the element exists in both input and output. Defaults to false.
  • visible: Hides or shows an element in the output. Defaults to true.
  • cardinality: Allows setting this element to allow a single or multiple elements. See ElementMetadata.Cardinality for the valid values. Defaults to SINGLE.
  • contentRequired: Sets the text content for this element to required. Defaults to true if the ElementKey has a datatype other than Void.
  • validator: Overrides the validator for this element. By default a MetadataValidator is used.
  • properties: Additional properties used during parsing and generation. Different wire formats support different properties. Defaults to null.
  • valueTransform: Allows changing where the value of the element comes from. By default the value comes from the text content field, but this can be overridden by using a Metadata.VirtualValue.
  • attributes: The ordered set of attributes expected for this element. Defaults to empty. Adding an attribute can be accomplished by calling either addAttribute(AttributeKey) or replaceAttribute(AttributeKey), based on the desired order in the output.
  • elements: The ordered set of child elements expected for this element. Defaults to empty. Adding an element can be accomplished by calling either addElement(ElementKey) or replaceElement(ElementKey), based on the desired order in the output.
  • adaptations: A map from adaptation key to adaptation. An adaptation allows parsing into a generic base class and adapting the element into an appropriate subclass based on key.

Summary

Public Methods
abstract ElementCreator adapt(String kind, ElementKey<?, ?> adaptation)
Adds an adaptation from the element type of this element to the adaptation type.
abstract AttributeCreator addAttribute(AttributeKey<?> key)
Add the key for an attribute.
abstract ElementCreator addElement(ElementKey<?, ?> element)
Add the metadata for a child element.
abstract ElementCreator addUndeclaredAttributeMarker()
Sets the location of the undeclared attributes.
abstract ElementCreator addUndeclaredElementMarker()
Sets the location of the undeclared elements.
abstract ElementCreator blacklistElements(ElementKey...<?, ?> keys)
Blacklist a set of keys, these keys will be explicitly hidden from view.
abstract ElementCreator flatten()
Flattens this element.
abstract AttributeCreator moveAttribute(AttributeKey<?> key, Path path)
Adds a new virtual attribute based on a path.
abstract ElementCreator moveElement(ElementKey<?, ?> key, Path path)
Adds a new virtual element based on a path.
abstract ElementCreator orderAndWhitelistAttributes(AttributeKey...<?> keys)
Sets a list of attributes as the only visible attributes for an element, and also places them into the given order in the element.
abstract ElementCreator orderAndWhitelistElements(ElementKey...<?, ?> keys)
Sets a list of elements as the only visible child elements for an element, and also places them into the given order in the element.
abstract AttributeCreator replaceAttribute(AttributeKey<?> key)
Replaces the existing metadata for an attribute.
abstract ElementCreator replaceElement(ElementKey<?, ?> key)
Replaces the existing metadata for a child element.
abstract ElementCreator setCardinality(ElementMetadata.Cardinality cardinality)
Sets the cardinality of the element.
abstract ElementCreator setContentRequired(boolean contentRequired)
Sets whether the element's content is required.
abstract ElementCreator setMultipleVirtualElement(ElementMetadata.MultipleVirtualElement virtualElement)
Sets this metadata as representing a virtual element with multiple cardinality.
abstract ElementCreator setName(QName name)
Sets the name of the element.
abstract ElementCreator setProperties(Object properties)
Sets the element's properties.
abstract ElementCreator setRequired(boolean required)
Sets the requiredness of this element.
abstract ElementCreator setSingleVirtualElement(ElementMetadata.SingleVirtualElement virtualElement)
Sets this metadata as representing a virtual element with single cardinality.
abstract ElementCreator setValidator(ElementValidator validator)
Sets the element's validator.
abstract ElementCreator setVirtualValue(Metadata.VirtualValue virtualValue)
Sets the virtual text content of this element.
abstract ElementCreator setVisible(boolean visible)
Sets whether this element is visible.
abstract ElementCreator whitelistAttributes(AttributeKey...<?> keys)
Whitelists a set of attributes for this element metadata.
abstract ElementCreator whitelistElements(ElementKey...<?, ?> keys)
Whitelists a set of child elements for this element metadata.
[Expand]
Inherited Methods
From interface com.google.gdata.model.MetadataCreator

Public Methods

public abstract ElementCreator adapt (String kind, ElementKey<?, ?> adaptation)

Adds an adaptation from the element type of this element to the adaptation type. An adaptation is a customization of a base type to a particular variant type. Adaptations are used to allow adaptive parsing; the data is first parsed into the base type and then adapted to a more specific variant during resolution. If you are adding adaptations you should also override narrow(ElementMetadata, ValidationContext) and call adapt(Element, ElementMetadata, String) with the appropriate key.

Parameters
kind
adaptation

public abstract AttributeCreator addAttribute (AttributeKey<?> key)

Add the key for an attribute. If an attribute with the same ID already exists, the previous attribute will be removed, and the new attribute will be added to the end of the list. If you want to replace the existing element, use replaceAttribute(AttributeKey).

Parameters
key The key to the attribute that is being added.
Returns
  • an attribute builder that can be used to set the attribute fields.

public abstract ElementCreator addElement (ElementKey<?, ?> element)

Add the metadata for a child element. If an element with the same ID already exists, the previous element will be removed, and the new element will be added to the end of the list. If you want to replace the existing element, use replaceElement(ElementKey).

Parameters
element The key we are adding or pushing to the end.
Returns
  • the builder for the child element.

public abstract ElementCreator addUndeclaredAttributeMarker ()

Sets the location of the undeclared attributes. By default, undeclared attributes appear after all declared attributes, this lets them appear earlier in the list.

public abstract ElementCreator addUndeclaredElementMarker ()

Sets the location of the undeclared elements. By default, undeclared elements appear after all declared elements, this lets them appear earlier in the list.

public abstract ElementCreator blacklistElements (ElementKey...<?, ?> keys)

Blacklist a set of keys, these keys will be explicitly hidden from view.

Parameters
keys

public abstract ElementCreator flatten ()

Flattens this element. If the element has text content, this method will cause its text content to be output as part of any parent element, rather than as a separate nested element. Any attributes or child elements of this element will not be generated on output, if you wish to output those elements use the moveAttribute(AttributeKey, Path) and moveElement(ElementKey, Path) methods to place them somewhere else.

public abstract AttributeCreator moveAttribute (AttributeKey<?> key, Path path)

Adds a new virtual attribute based on a path. The path is relative to this element and must end in an attribute key. For example, if you want to add the atom:title@type attribute to entry, you could do:

registry.build(Entry.KEY).addVirtual( TextContent.TYPE, Path.of(Entry.TITLE, TextContent.TYPE));

Adding a virtual attribute will hide the source attribute in the output, but any changes made to the source will also be applied to the virtual location.

Parameters
key
path
Throws
IllegalArgumentException if the path does not end in an attribute.

public abstract ElementCreator moveElement (ElementKey<?, ?> key, Path path)

Adds a new virtual element based on a path. The path is relative to this element and must end in an element key. For example, if you want to add the media:keywords element to media:group, you could do:

registry.build(Entry.KEY).addVirtual( MediaKeyword.KEY, Path.of(MediaGroup.KEY, MediaKeyword.KEY));

Adding a virtual element will hide the source element in the output, but any changes made to the source will also be applied to the virtual location.

Parameters
key
path
Throws
IllegalArgumentException if the path does not end in an element.

public abstract ElementCreator orderAndWhitelistAttributes (AttributeKey...<?> keys)

Sets a list of attributes as the only visible attributes for an element, and also places them into the given order in the element.

Parameters
keys

public abstract ElementCreator orderAndWhitelistElements (ElementKey...<?, ?> keys)

Sets a list of elements as the only visible child elements for an element, and also places them into the given order in the element.

Parameters
keys

public abstract AttributeCreator replaceAttribute (AttributeKey<?> key)

Replaces the existing metadata for an attribute.

Parameters
key The key to the attribute that is being replaced.
Returns
  • an attribute builder that can be used to modify the attribute.

public abstract ElementCreator replaceElement (ElementKey<?, ?> key)

Replaces the existing metadata for a child element.

Parameters
key The key we are replacing.
Returns
  • this element metadata builder for chaining.
Throws
IllegalArgumentException if the child metadata doesn't exist.

public abstract ElementCreator setCardinality (ElementMetadata.Cardinality cardinality)

Sets the cardinality of the element. The cardinality can be either SINGLE for only a single element, or MULTIPLE for repeating elements.

Parameters
cardinality The cardinality of the element.
Returns
  • this element metadata builder for chaining.

public abstract ElementCreator setContentRequired (boolean contentRequired)

Sets whether the element's content is required. By default the content is required if the datatype is not Void.

Parameters
contentRequired True to set the content to required, false to set it to optional.
Returns
  • this element metadata builder for chaining.

public abstract ElementCreator setMultipleVirtualElement (ElementMetadata.MultipleVirtualElement virtualElement)

Sets this metadata as representing a virtual element with multiple cardinality. A virtual element is an element that only exists in the metadata, and is used during parsing and generation to map to the base DOM.

Parameters
virtualElement

public abstract ElementCreator setName (QName name)

Sets the name of the element. This can be used after copying some other metadata to change the name.

Parameters
name The new name to use for the element.
Returns
  • this metadata creator for chaining.

public abstract ElementCreator setProperties (Object properties)

Sets the element's properties. This is used to provide additional information during parsing/generation, and is specific to the wire format.

Parameters
properties Default properties for the element.
Returns
  • this element metadata builder for chaining.

public abstract ElementCreator setRequired (boolean required)

Sets the requiredness of this element. This means that the element must appear in the parent element for the parent element to be valid.

Parameters
required True to set the element to required, false to set it to optional (the default).
Returns
  • this metadata creator for chaining.

public abstract ElementCreator setSingleVirtualElement (ElementMetadata.SingleVirtualElement virtualElement)

Sets this metadata as representing a virtual element with single cardinality. A virtual element is an element that only exists in the metadata, and is used during parsing and generation to map to the base DOM.

Parameters
virtualElement

public abstract ElementCreator setValidator (ElementValidator validator)

Sets the element's validator. The validator is used to check that the element has all required attributes/elements/values. By default an instance of MetadataValidator is used.

Parameters
validator Element validator to use when validating the element, or null if no validation is needed (for undeclared metadata).
Returns
  • this element metadata builder for chaining.

public abstract ElementCreator setVirtualValue (Metadata.VirtualValue virtualValue)

Sets the virtual text content of this element. This can change how the text content of the element is rendered, but cannot be used for structural changes to the element. For that use setSingleVirtualElement(ElementMetadata.SingleVirtualElement) or setMultipleVirtualElement(ElementMetadata.MultipleVirtualElement).

Parameters
virtualValue

public abstract ElementCreator setVisible (boolean visible)

Sets whether this element is visible. If the element is not visible then it will not be included in the output. This can be used to set the state of an element to hidden if it is not part of the default set of metadata.

Parameters
visible True to make the property visible (the default), false to hide it from the output.
Returns
  • this metadata creator for chaining.

public abstract ElementCreator whitelistAttributes (AttributeKey...<?> keys)

Whitelists a set of attributes for this element metadata. This will hide all declared attributes on the metadata instance that will be created from this builder. This will not change the current order.

Parameters
keys

public abstract ElementCreator whitelistElements (ElementKey...<?, ?> keys)

Whitelists a set of child elements for this element metadata. This will hide all declared child elements on the metadata instance that will be created from this builder. This will not change the current order.

Parameters
keys