ResourceIdentifier (concierge 0.1 API)

java.lang.Object
- net.oneandone.concierge.resource.ResourceIdentifier

```
public class ResourceIdentifier
extends java.lang.Object
```
This class implements our resource identifier pattern.
We have three types of resources:
1. elements are uniquely addressable resources
2. groups may contain multiple elements
3. extensions may provided additional information for elements
Elements may also contain further groups, which leads us to a pattern how to address resources.
- A resource identifier always starts with a group and may end anytime
- If something follows on a group it's always an element
- The next identifier to an element might be the name of a group or extension
- An extension must terminate the resource identifier
So a resource identifier might look like group1/id1/group2/id2/extension.
The scope of a resource identifier is a pair of group and an optional element identifier or the address of an extension. In the example above we see three scopes:
1. group1/id1
2. group2/id2
3. and extension
The resource identifier will be initialized with scope 1) and will return the scope on call of this method.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`java.lang.String[]`	`completeHierarchy()` Returns a copy the complete group and extension hierarchy.
`boolean`	`empty()` Returns `true` if this resource identifier is empty, otherwise `false`.
`ResourceIdentifier`	`extend(Element element)` Extends the current resource identifier by the specified element `Addressable.address()`.
`ResourceIdentifier`	`extend(java.lang.String extension)` Extends the current resource identifier by the specified extension.
`java.lang.String[]`	`extendedHierarchy(java.lang.String extension)` Extends the hierarchy of the current scope by the specified extensions and returns it.
`java.util.Collection<java.lang.String>`	`extensions()` Returns all extensions as specified by the `show` query parameter.
`Filters`	`filters()` Returns the filters instance for the current scope of `this` resource identifier.
`java.lang.String[]`	`get()` Returns a copy of the complete parsed URI.
`java.lang.String`	`groupIdentifier()` Returns the group identifier.
`boolean`	`hasElementIdentifier()` Returns `true` if there is an element identifier in the current scope, otherwise `false`.
`boolean`	`hasNextScope()` Returns `true` if their are more scopes available, otherwise `false`.
`java.lang.String[]`	`hierarchy()` Returns the hierarchy for the current scope.
`ResourceIdentifier`	`next()` Returns the resource identifier for the next scope.
`static ResourceIdentifier`	`parse(java.lang.String uri)` Parses the specified URI and returns the resource identifier.
`static ResourceIdentifier`	`parse(java.lang.String uri, com.google.common.collect.Multimap<java.lang.String,java.lang.String> parameters)` Parses the specified URI and returns the resource identifier.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - parse
```
public static ResourceIdentifier parse(java.lang.String uri)
```
    Parses the specified URI and returns the resource identifier.
    
    Parameters:
    
    uri - the URI to parse
    
    Returns:
    
    the resource identifier for the specified URI
  - parse
```
public static ResourceIdentifier parse(java.lang.String uri,
                                       com.google.common.collect.Multimap<java.lang.String,java.lang.String> parameters)
```
    Parses the specified URI and returns the resource identifier.
    
    Parameters:
    
    uri - the URI to parse
    
    parameters - the request parameters
    
    Returns:
    
    the resource identifier for the specified URI
  - get
```
public java.lang.String[] get()
```
    Returns a copy of the complete parsed URI.
    
    Returns:
    
    the complete parsed URI
  - empty
```
public boolean empty()
```
    Returns true if this resource identifier is empty, otherwise false.
    
    Returns:
    
    true if this resource identifier is empty, otherwise false
  - hierarchy
```
public java.lang.String[] hierarchy()
```
    Returns the hierarchy for the current scope.
    The scope is initially set to the root of the URI and will be iterated within the result of each call on next().
    
    Returns:
    
    the hierarchy for the current scope
    
    See Also:
    
    completeHierarchy()
  - extendedHierarchy
```
public java.lang.String[] extendedHierarchy(java.lang.String extension)
```
    Extends the hierarchy of the current scope by the specified extensions and returns it.
    
    Parameters:
    
    extension - the extension name
    
    Returns:
    
    the extended hierarchy for the current scope
    
    See Also:
    
    hierarchy()
  - completeHierarchy
```
public java.lang.String[] completeHierarchy()
```
    Returns a copy the complete group and extension hierarchy.
    An URI of group1/id1/group2/id2/extension will return group1/group2/extension.
    
    Returns:
    
    the complete group and extension hierarchy
  - hasNextScope
```
public boolean hasNextScope()
```
    Returns true if their are more scopes available, otherwise false.
    
    Returns:
    
    true if their are more scopes available, otherwise false
  - next
```
public ResourceIdentifier next()
```
    Returns the resource identifier for the next scope.
    The scope is a pair of group and an optional element identifier or the address of an extension. E.g the URI group1/id1/group2/id2/extension has three scopes:
    1. group1/id1
    2. group2/id2
    3. and extension
    The resource identifier will be initialized with scope 1) and will return the scope on call of this method.
    Returns:
    
    the resource identifier for the next scope
  - hasElementIdentifier
```
public boolean hasElementIdentifier()
```
    Returns true if there is an element identifier in the current scope, otherwise false.
    
    Returns:
    
    true if there is an element identifier in the current scope, otherwise false
  - groupIdentifier
```
public java.lang.String groupIdentifier()
```
    Returns the group identifier.
    
    Returns:
    
    the group identifier
  - extend
```
public ResourceIdentifier extend(java.lang.String extension)
```
    Extends the current resource identifier by the specified extension.
    Extensions are only available for elements. If the extend operation will be called for a group or an extension an IllegalArgumentException will be thrown instead.
    
    Parameters:
    
    extension - the extension name
    
    Returns:
    
    the extended resource identifier
  - extend
```
public ResourceIdentifier extend(Element element)
```
    Extends the current resource identifier by the specified element Addressable.address().
    The current resource identifier can only be extended if no element identifier (see hasElementIdentifier()). If this resource identifier should be extended by an element and an element identifier already exists an IllegalArgumentException will be thrown.
    
    Parameters:
    
    element - the element to use for the extension
    
    Returns:
    
    the extended resource identifier
  - extensions
```
public java.util.Collection<java.lang.String> extensions()
```
    Returns all extensions as specified by the show query parameter.
    
    Returns:
    
    collection of all requested extensions
  - filters
```
public Filters filters()
```
    Returns the filters instance for the current scope of this resource identifier.
    See next() to learn more about the scope.
    
    Returns:
    
    the filters

Class ResourceIdentifier

Method Summary

Methods inherited from class java.lang.Object

Method Detail

parse

parse

get

empty

hierarchy

extendedHierarchy

completeHierarchy

hasNextScope

next

hasElementIdentifier

groupIdentifier

extend

extend

extensions

filters