Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.modeshape.graph
Class Location

    java.lang.Object
      org.modeshape.graph.Location

All Implemented Interfaces:
  Serializable, Comparable<Location>, Iterable<Property>

    @Immutable
    public abstract class Location

extends Object
implements Iterable<Property>, Comparable<Location>, Serializable

The location of a node, as specified by either its path, UUID, and/or identification properties. Hash codes are not implemented in this base class to allow immutable subclasses to calculate and cache the hash code during object construction.

See Also:
  Serialized Form

Field Summary
`protected static Iterator<Property>` | `NO_ID_PROPERTIES_ITERATOR` Simple shared iterator instance that is used when there are no properties.

Constructor Summary
`Location()`

Method Summary
`static Comparator<Location>` | `comparator()` Get a `Comparator` that can be used to compare two Location objects.
`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)` Two location objects are equal (or equivalent) if they share the same path and/or ID properties: if both locations have a path, they must have the same path; if both locations have ID properties, these properties must match.
`boolean` | `equals(Object obj, boolean requireSameNameSiblingIndexes)` Compare this location to the supplied location, and determine whether the two locations represent the same logical location.
`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.
`protected static UUID` | `identifierFor(Path identifierPath)`
`boolean` | `isSame(Location that)` Determine whether this location has the same `path` and `identification properties`: if one location has a path, then both must have the same path; likewise, if one location has ID properties, then both must have the same ID properties.
`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
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Field Detail

### NO_ID_PROPERTIES_ITERATOR

    protected static final Iterator<Property> NO_ID_PROPERTIES_ITERATOR

  Simple shared iterator instance that is used when there are no properties.

Constructor Detail

### Location

    public Location()

Method Detail

### comparator

    public static final Comparator<Location> comparator()

  Get a `Comparator` that can be used to compare two Location objects. Note that Location implements `Comparable` .

  Returns:
    the comparator; never null

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

### identifierFor

    protected static UUID identifierFor(Path identifierPath)

### 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 `ModeShapeLexicon.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 `ModeShapeLexicon.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 that)

  Determine whether this location has the same `path` and `identification properties`: if one location has a path, then both must have the same path; likewise, if one location has ID properties, then both must have the same ID properties.

  This is different than the behavior of `equals(Object)`, which attempts to determine whether two locations are equivalent. Two location objects are equivalent if they share the same path and/or ID properties: if both locations have a path, they must have the same path; if both locations have ID properties, these properties must match.

  Parameters:
    `that` - the other location to be compared
  Returns:
    true if they are the same, or false otherwise (or if the supplied location is null)
  See Also:
    `equals(Object)`

### 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)

  Two location objects are equal (or equivalent) if they share the same path and/or ID properties: if both locations have a path, they must have the same path; if both locations have ID properties, these properties must match.

  To determine whether two location objects represent the same location, use `isSame(Location)`: if one location has a path, then both must have the same path; likewise, if one location has ID properties, then both must have the same ID properties.

  Overrides:
    `equals` in class `Object`
  See Also:
    `Object.equals(java.lang.Object)`, `isSame(Location)`

### equals

    public boolean equals(Object obj,
                          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:
    `obj` - 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

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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