org.xbrlapi
Interface Fragment

All Superinterfaces:

Comparable<XML>, Serializable, XML

All Known Subinterfaces:

Arc, ArcEnd, ArcroleType, AttributeDeclaration, AttributeGroupDeclaration, ComplexTypeDeclaration, Concept, Context, ContextComponent, CustomType, Dimension, ElementDeclaration, Entity, EntityResource, ExplicitDimension, ExtendedLink, ExtendedLinkContent, Fact, FactDimensionContainer, FootnoteResource, FractionItem, Hypercube, Instance, Item, LabelResource, Language, Link, Linkbase, Locator, MeasureResource, MixedContentResource, Mock, NonNumericItem, NumericItem, OpenContextComponent, Period, ReferencePart, ReferencePartDeclaration, ReferenceResource, Resource, RoleType, Scenario, Schema, SchemaAllCompositor, SchemaChoiceCompositor, SchemaCompositor, SchemaContent, SchemaContentDeclaration, SchemaDeclaration, SchemaGroupCompositor, SchemaSequenceCompositor, Segment, SimpleLink, SimpleNumericItem, SimpleTypeDeclaration, Title, Tuple, TypedDimension, TypeDeclaration, Unit, UsedOn, XDTConcept, Xlink, XlinkDocumentation

All Known Implementing Classes:

ArcEndImpl, ArcImpl, ArcroleTypeImpl, AttributeDeclarationImpl, AttributeGroupDeclarationImpl, ComplexTypeDeclarationImpl, ConceptImpl, ContextComponentImpl, ContextImpl, CustomTypeImpl, DimensionImpl, ElementDeclarationImpl, EntityImpl, EntityResourceImpl, ExplicitDimensionImpl, ExtendedLinkContentImpl, ExtendedLinkImpl, FactDimensionContainerImpl, FactImpl, FootnoteResourceImpl, FractionItemImpl, FragmentImpl, HypercubeImpl, InstanceImpl, ItemImpl, LabelResourceImpl, LanguageImpl, LinkbaseImpl, LinkImpl, LocatorImpl, MeasureResourceImpl, MixedContentResourceImpl, MockImpl, NonNumericItemImpl, NumericItemImpl, OpenContextComponentImpl, PeriodImpl, ReferencePartDeclarationImpl, ReferencePartImpl, ReferenceResourceImpl, ResourceImpl, RoleTypeImpl, ScenarioImpl, SchemaAllCompositorImpl, SchemaChoiceCompositorImpl, SchemaCompositorImpl, SchemaContentDeclarationImpl, SchemaContentImpl, SchemaDeclarationImpl, SchemaGroupCompositorImpl, SchemaImpl, SchemaSequenceCompositorImpl, SegmentImpl, SimpleLinkImpl, SimpleNumericItemImpl, SimpleTypeDeclarationImpl, TitleImpl, TupleImpl, TypedDimensionImpl, TypeDeclarationImpl, UnitImpl, UsedOnImpl, XDTConceptImpl, XlinkDocumentationImpl

public interface Fragment
extends XML

Defines the functionality exposed by any fragment.

Author:

Geoff Shuetrim (geoff@galexy.net)

Method Summary

void	appendElementSchemeXPointer(String expression) Add an element Scheme XPointer Expression to the metadata.
void	appendID(String id) Add an ID (used in XPointer resolution) to the metadata.
List<Fragment>	getAllChildren() Gets all child fragments.
Set<String>	getAllChildrenIndices()
Fragment	getAncestorOrSelf(String type) Gets the ancestor (or self) fragment with the specified fragment type.
Fragment	getChild(String type, int index) Get a specific child fragment.
<F extends Fragment> List<F>	getChildren(Class<?> requiredClass) Gets the child fragments with the specified fragment type.
<F extends Fragment> List<F>	getChildren(String type) Gets the child fragments with the specified fragment type.
Set<String>	getChildrenIndices(String type)
Element	getDataRootElement() Get the root element of the fragment data.
String	getElementSchemeXPointerExpression()
String	getIDXPointerExpression()
List<LabelResource>	getLabels()
List<LabelResource>	getLabels(List<String> languages, List<URI> labelRoles)
List<LabelResource>	getLabels(List<String> languages, List<URI> labelRoles, List<URI> linkRoles)
List<LabelResource>	getLabelsWithLanguage(String language)
List<LabelResource>	getLabelsWithLanguageAndResourceRole(String language, URI role)
List<LabelResource>	getLabelsWithLanguageAndResourceRoleAndLinkRole(String language, URI resourceRole, URI linkRole)
List<LabelResource>	getLabelsWithResourceRole(URI role)
String	getLanguage()
String	getLanguage(Node node)
String	getLanguageName(List<String> languageNameEncodings)
String	getLanguageName(String languageNameEncoding)
String	getLocalname() Get the local name of the fragment's root element
String	getLocalnameFromQName(String qname) Returns the local name for a QName
URI	getNamespace() Get the namespace of the fragment root element.
URI	getNamespaceFromQName(String qname, Node node) Returns the Namespace for a QName in the context of a node in the fragment.
Fragment	getParent() Get the parent fragment of this fragment or null if there is none.
Element	getParentElement(Element parentDataRootElement) Get the element in the parent fragment that has this fragment as its child.
String	getParentIndex() Get the index of the parent fragment or null if the fragment does not have a parent fragment.
String	getPrefixFromQName(String qname) Returns the Namespace prefix for a QName
List<ReferenceResource>	getReferences()
List<ReferenceResource>	getReferencesWithLanguage(String language)
List<ReferenceResource>	getReferencesWithLanguageAndResourceRoleAndLinkRole(String language, URI resourceRole, URI linkRole)
List<ReferenceResource>	getReferencesWithLanguageAndRole(String language, URI role)
List<ReferenceResource>	getReferencesWithResourceRole(String role)
List<Locator>	getReferencingLocators() Retrieves a list of all locators that target this fragment.
String[]	getSequenceToParentElement() Get the sequence of steps through the parent fragment DOM to the parent element.
String	getSequenceToParentElementAsString()
List<SimpleLink>	getSimpleLinks()
URI	getURI() Get the URI of the document containing this fragment.
String	getXPath() Get the XPath to the element in the parent fragment that is the parent element of this fragment's root element.
String	getXPointerExpression()
boolean	isAncestorOf(Fragment descendant)
boolean	isChild()
boolean	isNewFragment() Tests if a fragment is new in the sense that it does not have a root data element.
boolean	isRoot()
void	setParentIndex(String index) Set the index of the parent fragment.
void	setSequenceToParentElement(Fragment parent) Specifies the set of ancestor elements of the element in the parent fragment that is the insertion point for this fragment's root element.
void	setURI(URI uri) Set the URI of the fragment's document.

Methods inherited from interface org.xbrlapi.XML

appendMetadataElement, equals, getBuilder, getDocumentNode, getIndex, getMetaAttribute, getMetadataRootElement, getStore, getType, hashCode, hasMetaAttribute, isa, isa, removeMetaAttribute, removeMetadataElement, serialize, serialize, serialize, setBuilder, setIndex, setMetaAttribute, setResource, setStore, updateInStore

Methods inherited from interface java.lang.Comparable

compareTo

Method Detail

getDataRootElement

Element getDataRootElement()
                           throws XBRLException

Get the root element of the fragment data.

Returns:

an XML Element that is the root of the fragment data.

Throws:

XBRLException - if the fragment does not have fragment data.

isNewFragment

boolean isNewFragment()
                      throws XBRLException

Tests if a fragment is new in the sense that it does not have a root data element. This is only used by the SAX content builder to keep track of where the fragment construction process is at.

Returns:

true if the fragment is new.

Throws:

XBRLException

getURI

URI getURI()
           throws XBRLException

Get the URI of the document containing this fragment.

Throws:

XBRLException

setURI

void setURI(URI uri)
            throws XBRLException

Set the URI of the fragment's document.

Parameters:

uri - The string value of the document's absolute URI

Throws:

XBRLException.

XBRLException

getReferencingLocators

List<Locator> getReferencingLocators()
                                     throws XBRLException

Retrieves a list of all locators that target this fragment.

Returns:

a list of all locators that target this fragment. The list can be empty.

Throws:

XBRLException.

XBRLException

getParentIndex

String getParentIndex()
                      throws XBRLException

Get the index of the parent fragment or null if the fragment does not have a parent fragment.

Returns:

The index of the parent fragment or null if the fragment does not have a parent fragment.

Throws:

XBRLException - if the parent fragment index is not available.

isRoot

boolean isRoot()
               throws XBRLException

Returns:

true if the fragment is the root of an XML document and false otherwise.

Throws:

XBRLException

See Also:

isChild()

getSequenceToParentElement

String[] getSequenceToParentElement()
                                    throws XBRLException

Get the sequence of steps through the parent fragment DOM to the parent element.

Returns:

The sequence through the parent fragment data to the parent element of this fragment.

Throws:

XBRLException

getSequenceToParentElementAsString

String getSequenceToParentElementAsString()
                                          throws XBRLException

Returns:

the sequence of steps through the parent fragment DOM to the parent element of this fragment.

Throws:

XBRLException

setParentIndex

void setParentIndex(String index)
                    throws XBRLException

Set the index of the parent fragment.

Parameters:

index - The index of the parent fragment.

Throws:

XBRLException - if the parent fragment index cannot be set.

getXPath

String getXPath()
                throws XBRLException

Get the XPath to the element in the parent fragment that is the parent element of this fragment's root element.

Returns:

The required xpath.

Throws:

XBRLException

setSequenceToParentElement

void setSequenceToParentElement(Fragment parent)
                                throws XBRLException

Specifies the set of ancestor elements of the element in the parent fragment that is the insertion point for this fragment's root element. The ancestor elements are identified by their sibling order in the parent fragment (after all other fragments have been carved out of it). Note that the root element of the parent fragment is not part of the sequence because that is always identified by a value of 1 - being an only child.

Parameters:

parent - The parent fragment.

Throws:

XBRLException

appendID

void appendID(String id)
              throws XBRLException

Add an ID (used in XPointer resolution) to the metadata.

Parameters:

id - The value of the ID.

Throws:

XBRLException.

XBRLException

appendElementSchemeXPointer

void appendElementSchemeXPointer(String expression)
                                 throws XBRLException

Add an element Scheme XPointer Expression to the metadata.

Parameters:

expression - The XPointer expression

Throws:

XBRLException

getXPointerExpression

String getXPointerExpression()
                             throws XBRLException

Returns:

the ID XPointer expression for this fragment or the element Scheme XPointer expression if there is no shorthand ID-based XPointer expression. What is returned is the entire string that is to be appended to the relevant URI to identify the fragment, including the # symbol and everything that follows it.

Throws:

XBRLException

getElementSchemeXPointerExpression

String getElementSchemeXPointerExpression()
                                          throws XBRLException

Returns:

the element scheme XPointer expression for this fragment.

Throws:

XBRLException

getIDXPointerExpression

String getIDXPointerExpression()
                               throws XBRLException

Returns:

the shorthand ID XPointer expression for this fragment or null if there is none.

Throws:

XBRLException

getNamespace

URI getNamespace()
                 throws XBRLException

Get the namespace of the fragment root element.

Throws:

XBRLException - if there is no data element in the fragment.

getLocalname

String getLocalname()
                    throws XBRLException

Get the local name of the fragment's root element

Throws:

XBRLException

getParentElement

Element getParentElement(Element parentDataRootElement)
                         throws XBRLException

Get the element in the parent fragment that has this fragment as its child.

Parameters:

parentDataRootElement - The root element of the parent fragment's data.

Returns:

the element of the parent fragment that has this fragment as its child (or null if no parent exists).

Throws:

XBRLException

getParent

Fragment getParent()
                   throws XBRLException

Get the parent fragment of this fragment or null if there is none.

Returns:

the parent fragment or null if none exists.

Throws:

XBRLException

isChild

boolean isChild()
                throws XBRLException

Returns:

true iff the fragment has a parent fragment and false otherwise.

Throws:

XBRLException

isAncestorOf

boolean isAncestorOf(Fragment descendant)
                     throws XBRLException

Parameters:

descendant - The candidate descendant fragment.

Returns:

true if the candidate descendant is actually a descendant fragment and false otherwise.

Throws:

XBRLException

getAllChildren

List<Fragment> getAllChildren()
                              throws XBRLException

Gets all child fragments.

Returns:

the fragment list of children fragments or the empty list if no child fragments exist in the data store.

Throws:

XBRLException

getAllChildrenIndices

Set<String> getAllChildrenIndices()
                                  throws XBRLException

Returns:

the set of indices of all child fragments of this fragment.

Throws:

XBRLException

getSimpleLinks

List<SimpleLink> getSimpleLinks()
                                throws XBRLException

Returns:

the list of simple links that are children of this fragment.

Throws:

XBRLException

getAncestorOrSelf

Fragment getAncestorOrSelf(String type)
                           throws XBRLException

Gets the ancestor (or self) fragment with the specified fragment type.

Parameters:

type - The required fragment type of the ancestor (or self).

Returns:

the first ancestor (or self) fragment that matches the specified fragment type working up the XML document structure from the supplied fragment to the root of the XML document. TODO Modify to use Generics so the fragment returned can be of a specific type.

Throws:

XBRLException - if no such ancestor fragment exists.

getNamespaceFromQName

URI getNamespaceFromQName(String qname,
                          Node node)
                          throws XBRLException

Returns the Namespace for a QName in the context of a node in the fragment.

Parameters:

qname - The qName value to resolve

node - The node in the fragment data (as a DOM representation) to start QName resolution from.

Returns:

the namespace declared on the fragment for the QName

Throws:

XBRLException - if the namespace is not declared

getLocalnameFromQName

String getLocalnameFromQName(String qname)

Returns the local name for a QName

Parameters:

qname - The qName value to resolve

Returns:

the local name for the QName.

getPrefixFromQName

String getPrefixFromQName(String qname)

Returns the Namespace prefix for a QName

Parameters:

qname - The qName value to resolve

Returns:

the namespace prefix in the QName

Throws:

XBRLException

getLabels

List<LabelResource> getLabels()
                              throws XBRLException

Returns:

a list of label resources for the fragment.

Throws:

XBRLException

getLabelsWithResourceRole

List<LabelResource> getLabelsWithResourceRole(URI role)
                                              throws XBRLException

Parameters:

role - The XLink role value

Returns:

the list of labels for this fragment with the specified XLink role.

Throws:

XBRLException

getLabels

List<LabelResource> getLabels(List<String> languages,
                              List<URI> labelRoles)
                              throws XBRLException

Parameters:

languages - the list of language codes in order of preference from most preferred to least preferred, eventually allowing any language if no explicit preference match.

labelRoles - the list of label resource roles in order of preference from most preferred to least preferred, eventually allowing any resource role.

Returns:

the list of labels that best match the specified search criteria. Note that a label role preference which takes precedence over a language preference.

Throws:

XBRLException

getLabels

List<LabelResource> getLabels(List<String> languages,
                              List<URI> labelRoles,
                              List<URI> linkRoles)
                              throws XBRLException

Parameters:

languages - the list of language codes in order of preference from most preferred to least preferred, eventually allowing any language if no explicit preference match.

labelRoles - the list of label resource roles in order of preference from most preferred to least preferred, eventually allowing any resource role.

linkRoles - the list of extended link roles in order of preference from most preferred to least preferred, eventually allowing any link role.

Returns:

the list of labels that best match the specified search criteria. Note that a link role preference takes precedence over a label role preference which takes precedence over a language preference. Note also that if none of the preferences are met, an attempt is still made to return a list of all labels in the data store for this fragment.

Throws:

XBRLException

getReferencesWithResourceRole

List<ReferenceResource> getReferencesWithResourceRole(String role)
                                                      throws XBRLException

Parameters:

role - The XLink role value

Returns:

the list of references for this fragment with the specified XLink role.

Throws:

XBRLException

getLabelsWithLanguage

List<LabelResource> getLabelsWithLanguage(String language)
                                          throws XBRLException

Parameters:

language - The xml:lang language codevalue

Returns:

the list of labels for this fragment with the specified language code.

Throws:

XBRLException

getLabelsWithLanguageAndResourceRole

List<LabelResource> getLabelsWithLanguageAndResourceRole(String language,
                                                         URI role)
                                                         throws XBRLException

Parameters:

language - The xml:lang language code value

role - The XLink role value

Returns:

the list of labels for this fragment with the specified language code and XLink role.

Throws:

XBRLException

getLabelsWithLanguageAndResourceRoleAndLinkRole

List<LabelResource> getLabelsWithLanguageAndResourceRoleAndLinkRole(String language,
                                                                    URI resourceRole,
                                                                    URI linkRole)
                                                                    throws XBRLException

Parameters:

language - The xml:lang language code value or null if not used as a a label selection criterion.

resourceRole - The XLink resource role value on the label or null if not used as a a label selection criterion.

linkRole - The XLink extended link role value on the extended link containing the label or null if not used as a a label selection criterion..

Returns:

the list of labels for this fragment that match the specified criteria.

Throws:

XBRLException

getReferences

List<ReferenceResource> getReferences()
                                      throws XBRLException

Returns:

a list of references for the fragment based on XBRL 2.1 reference arcs.

Throws:

XBRLException

getReferencesWithLanguage

List<ReferenceResource> getReferencesWithLanguage(String language)
                                                  throws XBRLException

Parameters:

language - The xml:lang language code value

Returns:

the list of references for this fragment with the specified language code.

Throws:

XBRLException

getReferencesWithLanguageAndRole

List<ReferenceResource> getReferencesWithLanguageAndRole(String language,
                                                         URI role)
                                                         throws XBRLException

Parameters:

language - The xml:lang language code value

role - The XLink role value

Returns:

the list of references for this fragment with the specified language code and XLink role.

Throws:

XBRLException

getReferencesWithLanguageAndResourceRoleAndLinkRole

List<ReferenceResource> getReferencesWithLanguageAndResourceRoleAndLinkRole(String language,
                                                                            URI resourceRole,
                                                                            URI linkRole)
                                                                            throws XBRLException

Parameters:

language - The xml:lang language code value

resourceRole - The XLink resource role value on the reference

linkRole - The XLink extended link role value on the extended link containing the reference.

Returns:

the list of references for this fragment with the specified language code and XLink resource and link roles.

Throws:

XBRLException

getChild

Fragment getChild(String type,
                  int index)
                  throws XBRLException

Get a specific child fragment.

Parameters:

type - The fragment type of the required child

index - The index of the required child fragment (among other children of the same type) with the first child being at index 0.

Returns:

the child fragment or null if there are no children fragments of the specified type.

Throws:

XBRLException - if the index is out of bounds

getChildren

<F extends Fragment> List<F> getChildren(String type)
                                     throws XBRLException

Gets the child fragments with the specified fragment type.

Parameters:

type - The required fragment type of the child. EG: If a list of org.xbrlapi.impl.ReferenceArcImpl fragments is required then this parameter would have a value of "ReferenceArc". Note that if the parameter contains full stops, then it is used directly as the value for the fragment type, enabling fragment extensions to exploit this method without placing fragment implementations in the org.xbrlapi package.

Returns:

the fragment list of children fragments that match the specified fragment type

Throws:

XBRLException

getChildren

<F extends Fragment> List<F> getChildren(Class<?> requiredClass)
                                     throws XBRLException

Gets the child fragments with the specified fragment type.

Parameters:

requiredClass - The required fragment class of the child fragments.

Returns:

the fragment list of children fragments that match the specified fragment type

Throws:

XBRLException

getChildrenIndices

Set<String> getChildrenIndices(String type)
                               throws XBRLException

Parameters:

type - The fragment type

Returns:

The list of all fragments of the given fragment type.

Throws:

XBRLException

getLanguage

String getLanguage(Node node)
                   throws XBRLException

Parameters:

node - The XML node to get the XML language fragment for.

Returns:

the value of the xml:lang attribute applying to the given node or null if no such attribute is applicable.

Throws:

XBRLException

getLanguage

String getLanguage()
                   throws XBRLException

Returns:

the value of the xml:lang attribute applying to the fragment root element or null if no such attribute is applicable. This takes into account xml:lang attribute inheritance though the XML heirarchy within an XML document.

Throws:

XBRLException

getLanguageName

String getLanguageName(String languageNameEncoding)
                       throws XBRLException

Parameters:

languageNameEncoding - The language encoding of the language name, available in the data store in the form of a Language XML resource.

Returns:

the name of the language used for the fragment or null if none is specified or no appropriate Language resource is available in the data store.

Throws:

XBRLException

See Also:

for details of these objects.

getLanguageName

String getLanguageName(List<String> languageNameEncodings)
                       throws XBRLException

Returns:

the name of the language used for the fragment or null if none is specified or none is available. The name is obtained by working through the list of language encodings from first to last, returning the first name that is available in the data store in the form of a Language XML resource.

Throws:

XBRLException