org.jboss.dna.graph
Class Location

java.lang.Object
  extended by org.jboss.dna.graph.Location
All Implemented Interfaces:
Comparable<Location>, Iterable<Property>

@Immutable
public abstract class Location
extends Object
implements Iterable<Property>, Comparable<Location>

The location of a node, as specified by either its path, UUID, and/or identification properties.


Constructor Summary
Location()
           
 
Method Summary
 int compareTo(Location that)
          
static Location create(Iterable<Property> idProperties)
          Create a location defined by a path and an iterator over identification properties.
static Location create(List<Property> idProperties)
          Create a location defined by multiple identification properties.
static Location create(Path path)
          Create a location defined by a path.
static Location create(Path path, Iterable<Property> idProperties)
          Create a location defined by a path and an iterator over identification properties.
static Location create(Path path, Property idProperty)
          Create a location defined by a path and a single identification property.
static Location create(Path path, Property firstIdProperty, Property... remainingIdProperties)
          Create a location defined by a path and multiple identification properties.
static Location create(Path path, UUID uuid)
          Create a location defined by a path and an UUID.
static Location create(Property idProperty)
          Create a location defined by a single identification property.
static Location create(Property firstIdProperty, Property... remainingIdProperties)
          Create a location defined by multiple identification properties.
static Location create(UUID uuid)
          Create a location defined by a UUID.
 boolean equals(Object obj)
          
abstract  List<Property> getIdProperties()
          Get the identification properties that (at least in part) define this location.
 Property getIdProperty(Name name)
          Get the identification property with the supplied name, if there is such a property.
abstract  Path getPath()
          Get the path that (at least in part) defines this location.
 String getString()
          Get the string form of the location.
 String getString(NamespaceRegistry namespaceRegistry)
          Get the encoded string form of the location, using the supplied encoder to encode characters in each of the location's path and properties.
 String getString(NamespaceRegistry namespaceRegistry, TextEncoder encoder)
          Get the encoded string form of the location, using the supplied encoder to encode characters in each of the location's path and properties.
 String getString(NamespaceRegistry namespaceRegistry, TextEncoder encoder, TextEncoder delimiterEncoder)
          Get the encoded string form of the location, using the supplied encoder to encode characters in each of the location's path and properties.
 String getString(TextEncoder encoder)
          Get the encoded string form of the location, using the supplied encoder to encode characters in each of the location's path and properties.
 UUID getUuid()
          Get the first UUID that is in one of the identification properties.
 int hashCode()
          
 boolean hasIdProperties()
          Return whether this location is defined (at least in part) with identification properties.
 boolean hasPath()
          Return whether this location is defined (at least in part) by a path.
 boolean isSame(Location other)
          Compare this location to the supplied location, and determine whether the two locations represent the same logical location.
 boolean isSame(Location other, boolean requireSameNameSiblingIndexes)
          Compare this location to the supplied location, and determine whether the two locations represent the same logical location.
 Iterator<Property> iterator()
          
 String toString()
          
abstract  Location with(Path newPath)
          Create a copy of this location that uses the supplied path.
abstract  Location with(Property newIdProperty)
          Create a copy of this location that adds the supplied identification property.
abstract  Location with(UUID uuid)
          Create a copy of this location that adds the supplied UUID as an identification property.
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Location

public Location()
Method Detail

create

public static Location create(Path path)
Create a location defined by a path.

Parameters:
path - the path
Returns:
a new Location with the given path and no identification properties
Throws:
IllegalArgumentException - if path is null

create

public static Location create(UUID uuid)
Create a location defined by a UUID.

Parameters:
uuid - the UUID
Returns:
a new Location with no path and a single identification property with the name DnaLexicon.UUID and the given uuid for a value.
Throws:
IllegalArgumentException - if uuid is null

create

public static Location create(Path path,
                              UUID uuid)
Create a location defined by a path and an UUID.

Parameters:
path - the path
uuid - the UUID, or null if there is no UUID
Returns:
a new Location with the given path (if any) and a single identification property with the name DnaLexicon.UUID and the given uuid (if it is present) for a value.
Throws:
IllegalArgumentException - if path is null

create

public static Location create(Path path,
                              Property idProperty)
Create a location defined by a path and a single identification property.

Parameters:
path - the path
idProperty - the identification property
Returns:
a new Location with the given path and identification property (if it is present).
Throws:
IllegalArgumentException - if path or idProperty is null

create

public static Location create(Path path,
                              Property firstIdProperty,
                              Property... remainingIdProperties)
Create a location defined by a path and multiple identification properties.

Parameters:
path - the path
firstIdProperty - the first identification property
remainingIdProperties - the remaining identification property
Returns:
a new Location with the given path and identification properties.
Throws:
IllegalArgumentException - if any of the arguments are null

create

public static Location create(Path path,
                              Iterable<Property> idProperties)
Create a location defined by a path and an iterator over identification properties.

Parameters:
path - the path
idProperties - the iterator over the identification properties
Returns:
a new Location with the given path and identification properties
Throws:
IllegalArgumentException - if any of the arguments are null

create

public static Location create(Property idProperty)
Create a location defined by a single identification property.

Parameters:
idProperty - the identification property
Returns:
a new Location with no path and the given identification property.
Throws:
IllegalArgumentException - if idProperty is null

create

public static Location create(Property firstIdProperty,
                              Property... remainingIdProperties)
Create a location defined by multiple identification properties.

Parameters:
firstIdProperty - the first identification property
remainingIdProperties - the remaining identification property
Returns:
a new Location with no path and the given and identification properties.
Throws:
IllegalArgumentException - if any of the arguments are null

create

public static Location create(Iterable<Property> idProperties)
Create a location defined by a path and an iterator over identification properties.

Parameters:
idProperties - the iterator over the identification properties
Returns:
a new Location with no path and the given identification properties.
Throws:
IllegalArgumentException - if any of the arguments are null

create

public static Location create(List<Property> idProperties)
Create a location defined by multiple identification properties. This method does not check whether the identification properties are duplicated.

Parameters:
idProperties - the identification properties
Returns:
a new Location with no path and the given identification properties.
Throws:
IllegalArgumentException - if idProperties is null or empty

getPath

public abstract Path getPath()
Get the path that (at least in part) defines this location.

Returns:
the path, or null if this location is not defined with a path

hasPath

public boolean hasPath()
Return whether this location is defined (at least in part) by a path.

Returns:
true if a path helps define this location

getIdProperties

public abstract List<Property> getIdProperties()
Get the identification properties that (at least in part) define this location.

Returns:
the identification properties, or null if this location is not defined with identification properties

hasIdProperties

public boolean hasIdProperties()
Return whether this location is defined (at least in part) with identification properties.

Returns:
true if a identification properties help define this location

getIdProperty

public Property getIdProperty(Name name)
Get the identification property with the supplied name, if there is such a property.

Parameters:
name - the name of the identification property
Returns:
the identification property with the supplied name, or null if there is no such property (or if there are no identification properties

getUuid

public UUID getUuid()
Get the first UUID that is in one of the identification properties.

Returns:
the UUID for this location, or null if there is no such identification property

isSame

public boolean isSame(Location other)
Compare this location to the supplied location, and determine whether the two locations represent the same logical location. One location is considered the same as another location when one location is a superset of the other. For example, consider the following locations: Locations C and D would be considered the same, and B and D would also be considered the same. None of the other combinations would be considered the same.

Note that passing a null location as a parameter will always return false.

Parameters:
other - the other location to compare
Returns:
true if the two locations represent the same location, or false otherwise

isSame

public boolean isSame(Location other,
                      boolean requireSameNameSiblingIndexes)
Compare this location to the supplied location, and determine whether the two locations represent the same logical location. One location is considered the same as another location when one location is a superset of the other. For example, consider the following locations: Locations C and D would be considered the same, and B and D would also be considered the same. None of the other combinations would be considered the same.

Note that passing a null location as a parameter will always return false.

Parameters:
other - the other location to compare
requireSameNameSiblingIndexes - true if the paths must have equivalent same-name-sibling indexes, or false if the same-name-siblings may be different
Returns:
true if the two locations represent the same location, or false otherwise

iterator

public Iterator<Property> iterator()

Specified by:
iterator in interface Iterable<Property>
See Also:
Iterable.iterator()

hashCode

public int hashCode()

Overrides:
hashCode in class Object
See Also:
Object.hashCode()

equals

public boolean equals(Object obj)

Overrides:
equals in class Object
See Also:
Object.equals(java.lang.Object)

compareTo

public int compareTo(Location that)

Specified by:
compareTo in interface Comparable<Location>
See Also:
Comparable.compareTo(java.lang.Object)

getString

public String getString()
Get the string form of the location.

Returns:
the string
See Also:
getString(TextEncoder), getString(NamespaceRegistry), getString(NamespaceRegistry, TextEncoder), getString(NamespaceRegistry, TextEncoder, TextEncoder)

getString

public String getString(TextEncoder encoder)
Get the encoded string form of the location, using the supplied encoder to encode characters in each of the location's path and properties.

Parameters:
encoder - the encoder to use, or null if the default encoder should be used
Returns:
the encoded string
See Also:
getString(), getString(NamespaceRegistry), getString(NamespaceRegistry, TextEncoder), getString(NamespaceRegistry, TextEncoder, TextEncoder)

getString

public String getString(NamespaceRegistry namespaceRegistry)
Get the encoded string form of the location, using the supplied encoder to encode characters in each of the location's path and properties.

Parameters:
namespaceRegistry - the namespace registry to use for getting the string form of the path and properties, or null if no namespace registry should be used
Returns:
the encoded string
See Also:
getString(), getString(TextEncoder), getString(NamespaceRegistry, TextEncoder), getString(NamespaceRegistry, TextEncoder, TextEncoder)

getString

public String getString(NamespaceRegistry namespaceRegistry,
                        TextEncoder encoder)
Get the encoded string form of the location, using the supplied encoder to encode characters in each of the location's path and properties.

Parameters:
namespaceRegistry - the namespace registry to use for getting the string form of the path and properties, or null if no namespace registry should be used
encoder - the encoder to use, or null if the default encoder should be used
Returns:
the encoded string
See Also:
getString(), getString(TextEncoder), getString(NamespaceRegistry), getString(NamespaceRegistry, TextEncoder, TextEncoder)

getString

public String getString(NamespaceRegistry namespaceRegistry,
                        TextEncoder encoder,
                        TextEncoder delimiterEncoder)
Get the encoded string form of the location, using the supplied encoder to encode characters in each of the location's path and properties.

Parameters:
namespaceRegistry - the namespace registry to use for getting the string form of the path and properties, or null if no namespace registry should be used
encoder - the encoder to use, or null if the default encoder should be used
delimiterEncoder - the encoder to use for encoding the delimiters in paths, names, and properties, or null if the standard delimiters should be used
Returns:
the encoded string
See Also:
getString(), getString(TextEncoder), getString(NamespaceRegistry), getString(NamespaceRegistry, TextEncoder)

toString

public String toString()

Overrides:
toString in class Object
See Also:
Object.toString()

with

public abstract Location with(Property newIdProperty)
Create a copy of this location that adds the supplied identification property. The new identification property will replace any existing identification property with the same name on the original.

Parameters:
newIdProperty - the new identification property, which may be null
Returns:
the new location, or this location if the new identification property is null or empty

with

public abstract Location with(Path newPath)
Create a copy of this location that uses the supplied path.

Parameters:
newPath - the new path for the location
Returns:
the new location, or this location if the path is equal to this location's path

with

public abstract Location with(UUID uuid)
Create a copy of this location that adds the supplied UUID as an identification property. The new identification property will replace any existing identification property with the same name on the original.

Parameters:
uuid - the new UUID, which may be null
Returns:
the new location, or this location if the new identification property is null or empty


Copyright © 2008-2009 JBoss, a division of Red Hat. All Rights Reserved.