org.xbrlapi.aspects
Interface AspectModel

All Superinterfaces:

Serializable

All Known Subinterfaces:

DimensionalAspectModel

All Known Implementing Classes:

AspectModelImpl, DimensionalAspectModelImpl, DimensionalAspectModelWithMemoryCachingLabellers, DimensionalAspectModelWithStoreCachingLabellers, StandardAspectModel, StandardAspectModelWithMemoryCachingLabellers, StandardAspectModelWithStoreCachingLabellers

public interface AspectModel
extends Serializable

Aspect models

Aspect models are collections of aspects. They allow the aspects in the aspect model to be arranged into ordered groups, each of which is referred to as an axis of the aspect model. Aspect models imply no ordering over axes. Axes are useful in enabling structures like tabular representations of data to be defined. For example, by specifying a set of aspects as being in the column axis and another set of aspects as being in the row axis, it is possible to define a simple two dimensional table arrangement of XBRL facts.

Aspect models provide a means of getting the set of facts in the aspect model that are reported with specified values for a chosen set of aspects.

All aspect model classes need to have a constructor with a single parameter, that being the data store. @see org.xbrlapi.data.Store This constructor is used by the aspect model duplicate method.

Author:

Geoff Shuetrim (geoff@galexy.net)

Method Summary

void	addAspect(Aspect aspect) The aspect will be added as the last aspect in the default axis.
void	addAspect(Aspect parentAspect, Aspect aspect) The aspect will be added to the aspect model in the default axis and it will be immediately follow the parent aspect ID in the list of aspects associated with the default axis if that axis has the parent aspect in it.
void	addAspect(String axis, Aspect aspect) The aspect will be added as the last aspect in the given axis.
void	addAspect(String axis, Aspect parentAspect, Aspect aspect) The aspect will be added to the aspect model in the specified axis and it will be immediately follow the parent aspect ID in the list of aspects associated with the given axis if that axis has the parent aspect in it.
boolean	axisContainsAspect(String axis, URI aspectId)
AspectModel	duplicate()
Aspect	getAspect(URI aspectId)
String	getAspectLabel(URI aspectId, String locale, URI resourceRole, URI linkRole) This is a convenience method to give access to the labels generated by the labellers for each aspect in the aspect model.
Collection<Aspect>	getAspects()
List<Aspect>	getAspects(String axis)
String	getAspectValueLabel(AspectValue value, List<String> locales, List<URI> resourceRoles, List<URI> linkRoles) This is a convenience method to give access to the labels generated by the labellers for the values of each aspect in the aspect model.
String	getAspectValueLabel(AspectValue value, String locale, URI resourceRole, URI linkRole) This is a convenience method to give access to the labels generated by the labellers for the values of each aspect in the aspect model.
Map<URI,AspectValue>	getAspectValues(Context context)
Map<URI,AspectValue>	getAspectValues(Context context, Map<URI,AspectValue> existingValues)
Map<URI,AspectValue>	getAspectValues(Fact fact)
Map<URI,AspectValue>	getAspectValues(Fact fact, Map<URI,AspectValue> existingValues)
Map<URI,AspectValue>	getAspectValues(Unit unit)
Map<URI,AspectValue>	getAspectValues(Unit unit, Map<URI,AspectValue> existingValues)
Set<String>	getAxes()
String	getDefaultAxis()
Labeller	getLabeller(URI aspectId)
boolean	hasAspect(URI aspectId)
boolean	hasAxis(String axis)
boolean	hasLabeller(URI aspectId)
void	initialise() Initialises the aspects and the aspect value labellers in the aspect model.
void	moveAspects(String originalAxis, String newAxis)
void	setDefaultAxis(String defaultAxis)
void	setLabeller(URI aspectId, Labeller labeller)

Method Detail

initialise

void initialise()
                throws XBRLException

Initialises the aspects and the aspect value labellers in the aspect model. This should be called after the constructor has been run. Implementations of this class should always start by calling the initialise method of their super-class, if such a method exists. This use of initialise enables us to separate the resource intensive initialisation process from the constructor process. This can be useful if there are ways to avoid the initialisation process because of information that is already available, eg in another aspect model. In particular, this is useful for aspect model duplication.

Throws:

XBRLException

getAspects

Collection<Aspect> getAspects()
                              throws XBRLException

Returns:

a collection of all aspects in the aspect model, regardless of their axis.

Throws:

XBRLException

hasAspect

boolean hasAspect(URI aspectId)

Parameters:

aspectId - the aspect ID.

Returns:

true if the aspect model includes the aspect and false otherwise.

getAspect

Aspect getAspect(URI aspectId)
                 throws XBRLException

Parameters:

aspectId - the aspect ID.

Returns:

The aspect if it is in the model.

Throws:

XBRLException - if the aspect is not in the model.

getAspects

List<Aspect> getAspects(String axis)

Parameters:

axis - The unique (for the aspect model) identifier for an axis of the aspect model. Aspect models can have zero or more axes, each of which has an ordered sequence of aspects.

Returns:

the list of aspects for the specified axis. The list is empty if there are no aspects assigned to the chosen axis or the aspect model does not have the specified axis.

addAspect

void addAspect(String axis,
               Aspect aspect)

The aspect will be added as the last aspect in the given axis. If the aspect model does not already have the given axis, that axis will be added to the aspect model. If the aspect model does not have a labeller, the labeller for the aspect is set to the default labeller.

Parameters:

aspect - The aspect to add to the aspect model.

axis - the axis to put the aspect in, in last place in the ordering.

See Also:

LabellerImpl

addAspect

void addAspect(Aspect aspect)

The aspect will be added as the last aspect in the default axis. If the aspect model does not already have the default axis, that axis will be added to the aspect model.

Parameters:

aspect - The aspect to add to the aspect model.

addAspect

void addAspect(String axis,
               Aspect parentAspect,
               Aspect aspect)
               throws XBRLException

The aspect will be added to the aspect model in the specified axis and it will be immediately follow the parent aspect ID in the list of aspects associated with the given axis if that axis has the parent aspect in it. Otherwise the aspect will be added as the last aspect for the given axis. The labeller for the aspect is set to the default labeller.

Parameters:

axis - the axis to put the aspect in.

parentAspect - The parent aspect for the aspect being added.

aspect - The aspect to add to the aspect model.

Throws:

XBRLException

See Also:

LabellerImpl

addAspect

void addAspect(Aspect parentAspect,
               Aspect aspect)
               throws XBRLException

The aspect will be added to the aspect model in the default axis and it will be immediately follow the parent aspect ID in the list of aspects associated with the default axis if that axis has the parent aspect in it. Otherwise the aspect will be added as the last aspect for the default axis.

Parameters:

parentAspect - The parent aspect for the aspect being added.

aspect - The aspect to add to the aspect model.

Throws:

XBRLException

hasAxis

boolean hasAxis(String axis)
                throws XBRLException

Parameters:

axis - the axis.

Returns:

true if the aspect model has the specified axis and false otherwise.

Throws:

XBRLException

axisContainsAspect

boolean axisContainsAspect(String axis,
                           URI aspectId)

Parameters:

axis - The axis

aspectId - the aspect

Returns:

true if the axis is in the aspect model and contains the aspect and false otherwise.

getAxes

Set<String> getAxes()
                    throws XBRLException

Returns:

a set of strings, each of which is an axis of the aspect model.

Throws:

XBRLException

getDefaultAxis

String getDefaultAxis()

Returns:

the axis that new aspects are added to by default.

setDefaultAxis

void setDefaultAxis(String defaultAxis)
                    throws XBRLException

Parameters:

defaultAxis - the axis to add aspects to by default.

Throws:

XBRLException - if the axis is null.

getAspectValues

Map<URI,AspectValue> getAspectValues(Fact fact)
                                     throws XBRLException

Parameters:

fact - The fact to get the aspect values for.

Returns:

the map from Aspect IDs to values for those aspects, for the fact, with missing values for all aspects in the aspect model, that do not have a value for the given fact.

Throws:

XBRLException

getAspectValues

Map<URI,AspectValue> getAspectValues(Context context)
                                     throws XBRLException

Parameters:

context - The context to determine the aspect values from.

Returns:

the map of aspect values that can be constructed from the given context.

Throws:

XBRLException

getAspectValues

Map<URI,AspectValue> getAspectValues(Unit unit)
                                     throws XBRLException

Parameters:

unit - The unit to determine the aspect values from.

Returns:

the map of aspect values that can be constructed from the given unit.

Throws:

XBRLException

getAspectValues

Map<URI,AspectValue> getAspectValues(Unit unit,
                                     Map<URI,AspectValue> existingValues)
                                     throws XBRLException

Parameters:

unit - The unit to get the aspect values for.

existingValues - The map of aspect values that we already have and so do not need to get now.

Returns:

the map of existing and new aspect values, one for each aspect in this aspect model.

Throws:

XBRLException

getAspectValues

Map<URI,AspectValue> getAspectValues(Context context,
                                     Map<URI,AspectValue> existingValues)
                                     throws XBRLException

Parameters:

context - The context to get the aspect values for.

existingValues - The map of aspect values that we already have and so do not need to get now.

Returns:

the map of existing and new aspect values, one for each aspect in this aspect model.

Throws:

XBRLException

getAspectValues

Map<URI,AspectValue> getAspectValues(Fact fact,
                                     Map<URI,AspectValue> existingValues)
                                     throws XBRLException

Parameters:

fact - The fact to get the aspect values for.

existingValues - The map of aspect values that we already have and so do not need to get now.

Returns:

the map of existing and new aspect values, one for each aspect in this aspect model.

Throws:

XBRLException

moveAspects

void moveAspects(String originalAxis,
                 String newAxis)
                 throws XBRLException

Parameters:

originalAxis - The axis to move the aspects from

newAxis - The axis to move the aspects to

Throws:

XBRLException - if the original axis does not exist.

setLabeller

void setLabeller(URI aspectId,
                 Labeller labeller)
                 throws XBRLException

Parameters:

aspectId - The ID of the aspect that the labeller is to be used for.

labeller - The labeller to use.

Throws:

XBRLException - if a parameter is null or if the labeller is not for the specified aspect.

getLabeller

Labeller getLabeller(URI aspectId)
                     throws XBRLException

Parameters:

aspectId - The ID of the aspect to get the labeller for.

Returns:

the labeller for the specified aspect. If no labeller has been explicitly set for the aspect, then the default labeller is returned.

Throws:

XBRLException - if the aspect ID is null.

See Also:

LabellerImpl

hasLabeller

boolean hasLabeller(URI aspectId)

Parameters:

aspectId - The ID of the aspect.

Returns:

true if the aspect model already has a labeller for the specified aspect and false otherwise. Returns false if the aspect ID is null.

duplicate

AspectModel duplicate()
                      throws XBRLException

Returns:

a new aspect model that is a duplicate of this model. The aspects in the new aspect model are references to the same aspects as are in this aspect model (so this is not generating a real clone of the original aspect model) but the mapping from axis to aspects are cloned so that they can be changed in the duplicate aspect model without altering those mappings in the original aspect model. The data store is also not duplicated. In general, this does the work of the initialise method without doing a formal initialisation on the duplicate aspect model.

Throws:

XBRLException - if the aspect model does not support duplication.

getAspectLabel

String getAspectLabel(URI aspectId,
                      String locale,
                      URI resourceRole,
                      URI linkRole)
                      throws XBRLException

This is a convenience method to give access to the labels generated by the labellers for each aspect in the aspect model.

Parameters:

aspectId - the ID of the aspect being labelled.

locale - The label locale

resourceRole - The label XLink resource role

linkRole - The label link role

Returns:

the label for the given aspect.

Throws:

XBRLException - if the aspect is not in the aspect model.

getAspectValueLabel

String getAspectValueLabel(AspectValue value,
                           String locale,
                           URI resourceRole,
                           URI linkRole)
                           throws XBRLException

This is a convenience method to give access to the labels generated by the labellers for the values of each aspect in the aspect model.

Parameters:

value - The aspect value

locale - The label locale

resourceRole - The label XLink resource role

linkRole - The label link role

Returns:

the label for the given aspect value.

Throws:

XBRLException - if the aspect is not in the aspect model.

getAspectValueLabel

String getAspectValueLabel(AspectValue value,
                           List<String> locales,
                           List<URI> resourceRoles,
                           List<URI> linkRoles)
                           throws XBRLException

This is a convenience method to give access to the labels generated by the labellers for the values of each aspect in the aspect model.

Parameters:

value - The aspect value

locales - The list of label locales from first, most preferred to last, least preferred. The list can include nulls or it can be null.

resourceRoles - The list of label XLink resource roles from first, most preferred to last, least preferred. The list can include nulls or it can be null.

linkRoles - The label link role from first, most preferred to last, least preferred. The list can include nulls or it can be null.

Returns:

the label for the given aspect value.

Throws:

XBRLException - if the aspect is not in the aspect model.