com.google.gdata.model
Interface ElementCreator

All Superinterfaces:

MetadataCreator

public interface ElementCreator
extends MetadataCreator

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 ElementMetadata.Cardinality.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(com.google.gdata.model.AttributeKey) or replaceAttribute(com.google.gdata.model.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(com.google.gdata.model.ElementKey) or replaceElement(com.google.gdata.model.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.

Method Summary

ElementCreator	adapt(java.lang.String kind, ElementKey<?,?> adaptation) Adds an adaptation from the element type of this element to the adaptation type.
AttributeCreator	addAttribute(AttributeKey<?> key) Add the key for an attribute.
ElementCreator	addElement(ElementKey<?,?> element) Add the metadata for a child element.
ElementCreator	addUndeclaredAttributeMarker() Sets the location of the undeclared attributes.
ElementCreator	addUndeclaredElementMarker() Sets the location of the undeclared elements.
ElementCreator	blacklistElements(ElementKey<?,?>... keys) Blacklist a set of keys, these keys will be explicitly hidden from view.
ElementCreator	flatten() Flattens this element.
AttributeCreator	moveAttribute(AttributeKey<?> key, Path path) Adds a new virtual attribute based on a path.
ElementCreator	moveElement(ElementKey<?,?> key, Path path) Adds a new virtual element based on a path.
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.
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.
AttributeCreator	replaceAttribute(AttributeKey<?> key) Replaces the existing metadata for an attribute.
ElementCreator	replaceElement(ElementKey<?,?> key) Replaces the existing metadata for a child element.
ElementCreator	setCardinality(ElementMetadata.Cardinality cardinality) Sets the cardinality of the element.
ElementCreator	setContentRequired(boolean contentRequired) Sets whether the element's content is required.
ElementCreator	setMultipleVirtualElement(ElementMetadata.MultipleVirtualElement virtualElement) Sets this metadata as representing a virtual element with multiple cardinality.
ElementCreator	setName(QName name) Sets the name of the element.
ElementCreator	setProperties(java.lang.Object properties) Sets the element's properties.
ElementCreator	setRequired(boolean required) Sets the requiredness of this element.
ElementCreator	setSingleVirtualElement(ElementMetadata.SingleVirtualElement virtualElement) Sets this metadata as representing a virtual element with single cardinality.
ElementCreator	setValidator(ElementValidator validator) Sets the element's validator.
ElementCreator	setVirtualValue(Metadata.VirtualValue virtualValue) Sets the virtual text content of this element.
ElementCreator	setVisible(boolean visible) Sets whether this element is visible.
ElementCreator	whitelistAttributes(AttributeKey<?>... keys) Whitelists a set of attributes for this element metadata.
ElementCreator	whitelistElements(ElementKey<?,?>... keys) Whitelists a set of child elements for this element metadata.

Method Detail

setName

ElementCreator setName(QName name)

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

Specified by:

setName in interface MetadataCreator

Parameters:

name - the new name to use for the element.

Returns:

this metadata creator for chaining.

setRequired

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.

Specified by:

setRequired in interface MetadataCreator

Parameters:

required - true to set the element to required, false to set it to optional (the default).

Returns:

this metadata creator for chaining.

setVisible

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.

Specified by:

setVisible in interface MetadataCreator

Parameters:

visible - true to make the property visible (the default), false to hide it from the output.

Returns:

this metadata creator for chaining.

adapt

ElementCreator adapt(java.lang.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 Element.narrow(com.google.gdata.model.ElementMetadata, com.google.gdata.model.ValidationContext) and call Element.adapt(Element, ElementMetadata, String) with the appropriate key.

setCardinality

ElementCreator setCardinality(ElementMetadata.Cardinality cardinality)

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

Parameters:

cardinality - the cardinality of the element.

Returns:

this element metadata builder for chaining.

setContentRequired

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.

setValidator

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.

setProperties

ElementCreator setProperties(java.lang.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.

setVirtualValue

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(com.google.gdata.model.ElementMetadata.SingleVirtualElement) or setMultipleVirtualElement(com.google.gdata.model.ElementMetadata.MultipleVirtualElement).

Specified by:

setVirtualValue in interface MetadataCreator

setSingleVirtualElement

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.

setMultipleVirtualElement

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.

flatten

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(com.google.gdata.model.AttributeKey, com.google.gdata.model.Path) and moveElement(com.google.gdata.model.ElementKey, com.google.gdata.model.Path) methods to place them somewhere else.

moveAttribute

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.

Throws:

java.lang.IllegalArgumentException - if the path does not end in an attribute.

moveElement

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.

Throws:

java.lang.IllegalArgumentException - if the path does not end in an element.

addUndeclaredAttributeMarker

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.

addAttribute

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.

replaceAttribute

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.

orderAndWhitelistAttributes

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.

whitelistAttributes

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.

addUndeclaredElementMarker

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.

addElement

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.

replaceElement

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:

java.lang.IllegalArgumentException - if the child metadata doesn't exist.

orderAndWhitelistElements

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.

whitelistElements

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.

blacklistElements

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

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