org.xbrlapi

Interface Fragment

All Superinterfaces:

java.lang.Comparable<XML>, java.io.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

Methods

Modifier and Type	Method and Description
void	appendElementSchemeXPointer(java.lang.String expression) Add an element Scheme XPointer Expression to the metadata.
void	appendID(java.lang.String id) Add an ID (used in XPointer resolution) to the metadata.
java.util.List<Fragment>	getAllChildren() Gets all child fragments.
java.util.Set<java.lang.String>	getAllChildrenIndices()
Fragment	getAncestorOrSelf(java.lang.String type) Gets the ancestor (or self) fragment with the specified fragment type.
Fragment	getChild(java.lang.String type, int index) Get a specific child fragment.
<F extends Fragment> java.util.List<F>	getChildren(java.lang.Class<?> requiredClass) Gets the child fragments with the specified fragment type.
<F extends Fragment> java.util.List<F>	getChildren(java.lang.String type) Gets the child fragments with the specified fragment type.
java.util.Set<java.lang.String>	getChildrenIndices(java.lang.String type)
org.w3c.dom.Element	getDataRootElement() Get the root element of the fragment data.
java.lang.String	getElementSchemeXPointerExpression()
java.lang.String	getIDXPointerExpression()
java.util.List<LabelResource>	getLabels()
java.util.List<LabelResource>	getLabels(java.util.List<java.lang.String> languages, java.util.List<java.lang.String> labelRoles)
java.util.List<LabelResource>	getLabels(java.util.List<java.lang.String> languages, java.util.List<java.lang.String> labelRoles, java.util.List<java.lang.String> linkRoles)
java.util.List<LabelResource>	getLabelsWithLanguage(java.lang.String language)
java.util.List<LabelResource>	getLabelsWithLanguageAndResourceRole(java.lang.String language, java.lang.String role)
java.util.List<LabelResource>	getLabelsWithLanguageAndResourceRoleAndLinkRole(java.lang.String language, java.lang.String resourceRole, java.lang.String linkRole)
java.util.List<LabelResource>	getLabelsWithResourceRole(java.lang.String resourceRole)
java.lang.String	getLanguage()
java.lang.String	getLanguage(org.w3c.dom.Node node)
java.lang.String	getLanguageName(java.util.List<java.lang.String> languageNameEncodings)
java.lang.String	getLanguageName(java.lang.String languageNameEncoding)
java.lang.String	getLocalname() Get the local name of the fragment's root element
java.lang.String	getLocalnameFromQName(java.lang.String qname) Returns the local name for a QName
java.lang.String	getNamespace() Get the namespace of the fragment root element.
java.lang.String	getNamespaceFromQName(java.lang.String qname, org.w3c.dom.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.
org.w3c.dom.Element	getParentElement(org.w3c.dom.Element parentDataRootElement) Get the element in the parent fragment that has this fragment as its child.
java.lang.String	getParentIndex() Get the index of the parent fragment or null if the fragment does not have a parent fragment.
java.lang.String	getPrefixFromQName(java.lang.String qname) Returns the Namespace prefix for a QName
java.util.List<ReferenceResource>	getReferences()
java.util.List<ReferenceResource>	getReferencesWithLanguage(java.lang.String language)
java.util.List<ReferenceResource>	getReferencesWithLanguageAndResourceRoleAndLinkRole(java.lang.String language, java.net.URI resourceRole, java.net.URI linkRole)
java.util.List<ReferenceResource>	getReferencesWithLanguageAndRole(java.lang.String language, java.net.URI role)
java.util.List<ReferenceResource>	getReferencesWithResourceRole(java.lang.String role)
java.util.List<Locator>	getReferencingLocators() Retrieves a list of all locators that target this fragment.
java.lang.String[]	getSequenceToParentElement() Get the sequence of steps through the parent fragment DOM to the parent element.
java.lang.String	getSequenceToParentElementAsString()
java.util.List<SimpleLink>	getSimpleLinks()
java.net.URI	getURI() Get the URI of the document containing this fragment.
java.lang.String	getXPath() Get the XPath to the element in the parent fragment that is the parent element of this fragment's root element.
java.lang.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(java.lang.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(java.net.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

org.w3c.dom.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

java.net.URI getURI()
                    throws XBRLException

Get the URI of the document containing this fragment.

Throws:

XBRLException

setURI

void setURI(java.net.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

java.util.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

java.lang.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

java.lang.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

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

java.lang.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(java.lang.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(java.lang.String expression)
                                 throws XBRLException

Add an element Scheme XPointer Expression to the metadata.

Parameters:

expression - The XPointer expression

Throws:

XBRLException

getXPointerExpression

java.lang.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

java.lang.String getElementSchemeXPointerExpression()
                                                    throws XBRLException

Returns:

the element scheme XPointer expression for this fragment.

Throws:

XBRLException

getIDXPointerExpression

java.lang.String getIDXPointerExpression()
                                         throws XBRLException

Returns:

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

Throws:

XBRLException

getNamespace

java.lang.String getNamespace()
                              throws XBRLException

Get the namespace of the fragment root element.

Throws:

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

getLocalname

java.lang.String getLocalname()
                              throws XBRLException

Get the local name of the fragment's root element

Throws:

XBRLException

getParentElement

org.w3c.dom.Element getParentElement(org.w3c.dom.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

java.util.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

java.util.Set<java.lang.String> getAllChildrenIndices()
                                                      throws XBRLException

Returns:

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

Throws:

XBRLException

getSimpleLinks

java.util.List<SimpleLink> getSimpleLinks()
                                          throws XBRLException

Returns:

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

Throws:

XBRLException

getAncestorOrSelf

Fragment getAncestorOrSelf(java.lang.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

java.lang.String getNamespaceFromQName(java.lang.String qname,
                                     org.w3c.dom.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

java.lang.String getLocalnameFromQName(java.lang.String qname)

Returns the local name for a QName

Parameters:

qname - The qName value to resolve

Returns:

the local name for the QName.

getPrefixFromQName

java.lang.String getPrefixFromQName(java.lang.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

java.util.List<LabelResource> getLabels()
                                        throws XBRLException

Returns:

a list of label resources for the fragment.

Throws:

XBRLException

getLabelsWithResourceRole

java.util.List<LabelResource> getLabelsWithResourceRole(java.lang.String resourceRole)
                                                        throws XBRLException

Parameters:

resourceRole - The XLink role value

Returns:

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

Throws:

XBRLException

getLabels

java.util.List<LabelResource> getLabels(java.util.List<java.lang.String> languages,
                                      java.util.List<java.lang.String> 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

java.util.List<LabelResource> getLabels(java.util.List<java.lang.String> languages,
                                      java.util.List<java.lang.String> labelRoles,
                                      java.util.List<java.lang.String> 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

java.util.List<ReferenceResource> getReferencesWithResourceRole(java.lang.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

java.util.List<LabelResource> getLabelsWithLanguage(java.lang.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

java.util.List<LabelResource> getLabelsWithLanguageAndResourceRole(java.lang.String language,
                                                                 java.lang.String 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

java.util.List<LabelResource> getLabelsWithLanguageAndResourceRoleAndLinkRole(java.lang.String language,
                                                                            java.lang.String resourceRole,
                                                                            java.lang.String 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

java.util.List<ReferenceResource> getReferences()
                                                throws XBRLException

Returns:

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

Throws:

XBRLException

getReferencesWithLanguage

java.util.List<ReferenceResource> getReferencesWithLanguage(java.lang.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

java.util.List<ReferenceResource> getReferencesWithLanguageAndRole(java.lang.String language,
                                                                 java.net.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

java.util.List<ReferenceResource> getReferencesWithLanguageAndResourceRoleAndLinkRole(java.lang.String language,
                                                                                    java.net.URI resourceRole,
                                                                                    java.net.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(java.lang.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> java.util.List<F> getChildren(java.lang.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> java.util.List<F> getChildren(java.lang.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

java.util.Set<java.lang.String> getChildrenIndices(java.lang.String type)
                                                   throws XBRLException

Parameters:

type - The fragment type

Returns:

The list of all fragments of the given fragment type.

Throws:

XBRLException

getLanguage

java.lang.String getLanguage(org.w3c.dom.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

java.lang.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

java.lang.String getLanguageName(java.lang.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

java.lang.String getLanguageName(java.util.List<java.lang.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