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:


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.