org.jboss.dna.graph
Class Location

java.lang.Object
  org.jboss.dna.graph.Location

All Implemented Interfaces:

Iterable<Property>

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

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

Author:

Randall Hauch

Constructor Summary

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

Location(List<Property> idProperties)
Create a location defined by multiple identification properties.

Location(Path path)
Create a location defined by a path.

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

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

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

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

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

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

Location(UUID uuid)
Create a location defined by a UUID.

Method Summary

boolean	equals(Object obj)
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.
Path	getPath() Get the path that (at least in part) defines this location.
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()
Location	with(Path newPath) Create a copy of this location that uses the supplied path.
Location	with(Property newIdProperty) Create a copy of this location that adds the supplied identification property.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Location

public Location(Path path)

Create a location defined by a path.

Parameters:

path - the path

Throws:

IllegalArgumentException - if path is null

Location

public Location(UUID uuid)

Create a location defined by a UUID.

Parameters:

uuid - the UUID

Throws:

IllegalArgumentException - if uuid is null

Location

public Location(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

Throws:

IllegalArgumentException - if path is null

Location

public Location(Path path,
                Property idProperty)

Create a location defined by a path and a single identification property.

Parameters:

path - the path

idProperty - the identification property

Throws:

IllegalArgumentException - if path or idProperty is null

Location

public Location(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

Throws:

IllegalArgumentException - if any of the arguments are null

Location

public Location(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

Throws:

IllegalArgumentException - if any of the arguments are null

Location

public Location(Property idProperty)

Create a location defined by a single identification property.

Parameters:

idProperty - the identification property

Throws:

IllegalArgumentException - if idProperty is null

Location

public Location(Property firstIdProperty,
                Property... remainingIdProperties)

Create a location defined by multiple identification properties.

Parameters:

firstIdProperty - the first identification property

remainingIdProperties - the remaining identification property

Throws:

IllegalArgumentException - if any of the arguments are null

Location

public Location(Iterable<Property> idProperties)

Create a location defined by a path and an iterator over identification properties.

Parameters:

idProperties - the iterator over the identification properties

Throws:

IllegalArgumentException - if any of the arguments are null

Location

public Location(List<Property> idProperties)

Create a location defined by multiple identification properties.

Parameters:

idProperties - the identification properties

Throws:

IllegalArgumentException - if idProperties is null or empty

Method Detail

getPath

public 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 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

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:

• location A is defined with a "/x/y" path
• location B is defined with an identification property {id=3}
• location C is defined with a "/x/y/z"
• location D is defined with a "/x/y/z" path and an identification property {id=3}

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:

• location A is defined with a "/x/y" path
• location B is defined with an identification property {id=3}
• location C is defined with a "/x/y/z"
• location D is defined with a "/x/y/z" path and an identification property {id=3}

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)

toString

public String toString()

Overrides:

toString in class Object

See Also:

Object.toString()

with

public 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 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