ARoad0.gBase
Class NameImpl

java.lang.Object
  extended by ARoad0.gBase.NameImpl
All Implemented Interfaces:
ImmutableName, Name, java.io.Serializable, java.lang.Cloneable, java.lang.Comparable

public final class NameImpl
extends java.lang.Object
implements Name, java.io.Serializable

This class is responsible for managing the names for all the database objects. Examples of real name are "http://accbee.com", "c:\program files\access road", "net/users/john". The separator character depends on the ACS. All the real names are converted in Access Road names implemented by this class. The single separator in all the Access Road names is ':: '. Name follows the OMG CORBA Object Services Specification (OMG-COSS) for a naming service which names an object for later retrieval. Methods added to the OMG specification are extended(ImmutableName), extended(String), clone(), equals(), hashCode(), getSerialVersion(), getNameFromString(). It does NOT follow the JNDI name interface.

The name is an ordered list of components in a java.util.ArrayList. Each component is a string that may be null. Case must be respected. ':: ' is a forbidden component. It is controlled in every creating or updating method. The usual struture of an entity name is (IS name).(ACS name).(entity name) Normally, the usual name of an instance of Name is equals to name.lastComponent(). To remove any component, use without(). To add a component at the end, use an extended() method. To modify the last component, use without() then extended(). For more complex modifying operations, use the list returned by components().

With threads, the calls to the Name methods should be done in a block synchronized on the Name instance. If the name is used as a key in a map, it is much safer to avoid a mutable name. Use then the ImmutableName interface to construct the key. But the update will remain possible by casting the ImmutableName in Name. The hashcode() and equals() methods are coherent over serialization, then a map with a name key handles the same values.

Since:
0.4.0
See Also:
Serialized Form

Field Summary
static NameImpl EMPTY_INSTANCE
          A reusable empty instance for initialization, to avoid the use of 'new' for temporary values.
private  java.util.ArrayList fCompo_
          fCompo_ is an ArrayList that stores the name components.
private static int INCREMENT_CAPACITY
           
private static int INITIAL_CAPACITY
           
private static int PRIME
           
static java.io.ObjectStreamField[] serialPersistentFields
           
private static long serialVersionUID__
           
 
Constructor Summary
NameImpl()
           
NameImpl(java.util.ArrayList _components)
          The returned instance is empty if a component contains ':: '.
NameImpl(java.lang.String _st)
          Returns a new empty name if the parameter is null or contains ':: '.
 
Method Summary
 java.lang.Object clone()
          Get a clone of name.
 int compareTo(java.lang.Object o)
           
 java.lang.String component(int _i)
          Gets the component at a given position.
 java.util.List<java.lang.String> components()
          Faster than immutableComponents().
 boolean contains(ImmutableName _name)
           
 Name context()
          Get a copy of the current name less the last component.
 Name context(int _end)
          Gets a copy of the current name less some last components.
 boolean equals(java.lang.Object _obj)
          Compares the two names.
 Name extended(ImmutableName _name)
          For extending the current name.
 Name extended(java.lang.String _nc)
          For extending the current name.
static Name getNameFromString(java.lang.String _text)
          Gets the name from the string returned by toString().
 long getSerialVersionUID()
           
 int hashCode()
           
 java.util.List immutableComponents()
           
 boolean isEmpty()
           
 java.lang.String lastComponent()
          Gets the last component of the name.
 int noOfComponents()
           
 Name subname(int _start, int _end)
          Returns a new Name instance.
 java.lang.String toString()
          Gets a String representation with one leading whitespace and ':: ' at the end, or gets ' null '.
 Name without(Name _name)
          Caution: this method changes the instance.
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

serialVersionUID__

private static final long serialVersionUID__
See Also:
Constant Field Values

INITIAL_CAPACITY

private static final int INITIAL_CAPACITY
See Also:
Constant Field Values

INCREMENT_CAPACITY

private static final int INCREMENT_CAPACITY
See Also:
Constant Field Values

PRIME

private static final int PRIME
See Also:
Constant Field Values

fCompo_

private java.util.ArrayList fCompo_
fCompo_ is an ArrayList that stores the name components. With ArrayList, hashcode() and equals() are coherent over serialization, then a map with a name key handles the same values after its deserialization.


EMPTY_INSTANCE

public static final NameImpl EMPTY_INSTANCE
A reusable empty instance for initialization, to avoid the use of 'new' for temporary values. Caution: never change the state of the returned instance.


serialPersistentFields

public static final java.io.ObjectStreamField[] serialPersistentFields
Constructor Detail

NameImpl

public NameImpl()

NameImpl

public NameImpl(java.util.ArrayList _components)
The returned instance is empty if a component contains ':: '.

Parameters:
_components - contains only strings, without ':: '. _components is copied.

NameImpl

public NameImpl(java.lang.String _st)
Returns a new empty name if the parameter is null or contains ':: '.

Parameters:
_st - is the string name.
Method Detail

isEmpty

public final boolean isEmpty()
Specified by:
isEmpty in interface ImmutableName
Returns:
true if the name has no component, or if all components are null or equal to empty Strings.

context

public final Name context()
Description copied from interface: ImmutableName
Get a copy of the current name less the last component.

Specified by:
context in interface ImmutableName
Returns:
a copy of the current instance without the last component. May be null.

without

public final Name without(Name _name)
Caution: this method changes the instance.

Specified by:
without in interface Name
Parameters:
_name - is removed from the current name. _name may be at the start, the end or the middle of the current name. If there are several sections of the current name that are strictly identical to _name, without() removes the last matched part, at the end of the current name.
Returns:
this instance With threads, this non-synchronized method (for performance) must be used in a synchronized block. May be null.

extended

public final Name extended(java.lang.String _nc)
For extending the current name. Caution: this method updates the instance. Noop if the argument is null or empty, or if ':: ' is in the argument, because it is used in toString() and getNameFromString(). With threads, this method must be used in a synchronized block.

Specified by:
extended in interface Name
Parameters:
_nc - adds a new component to the current instance
Returns:
this instance

extended

public final Name extended(ImmutableName _name)
For extending the current name. The name is unchanged if _name is null or an empty instance, or has a component which contains ":: " (see getNameFromString()).

Specified by:
extended in interface Name
Parameters:
_name - adds a new name at the end of the current instance
Returns:
this instance
Since:
0.5.1

context

public final Name context(int _end)
Gets a copy of the current name less some last components.

Specified by:
context in interface ImmutableName
Parameters:
_end - is the _inclusive_ index of the last component to be returned
Returns:
the context (from 0 to _end) of the current name in a new Name, this name if _end = (size of the name) - 1, this name.context() if _end = (size of the name) - 2, the first name component if _end = 0. The context is not backed by the first components of the current name. Return is null if the name is empty, or if _end is equal or superior to the name size.

subname

public final Name subname(int _start,
                          int _end)
Returns a new Name instance. For instance, the name 'A' with 3 components '1', '2' and '3' returns a new name with 1 component '2' through the command A.subname(1, 2).

Specified by:
subname in interface ImmutableName
Specified by:
subname in interface Name
Parameters:
_start - inclusive fromIndex
_end - exclusive toIndex
Returns:
an extract of the current name that is copied in a new Name. May be null.

components

public final java.util.List<java.lang.String> components()
Faster than immutableComponents().

Specified by:
components in interface ImmutableName
Returns:
List of the components, as strings, that is backed by the list of the current name. Then, the returned name is modifiable but the only proprietary of the returned list is the current name. So, to avoid any bug, USE THE RETURNED LIST AS A TRANSIENT OBJECT, for a limited time. Never delete it directly. May be null.

immutableComponents

public final java.util.List immutableComponents()
Specified by:
immutableComponents in interface ImmutableName
Returns:
List of the components (strings) in the name. is immutable. may be null.

noOfComponents

public final int noOfComponents()
Specified by:
noOfComponents in interface ImmutableName
Returns:
int number of components in the name.

component

public final java.lang.String component(int _i)
Gets the component at a given position.

Specified by:
component in interface ImmutableName
Parameters:
_i - index of the component. No limit on the value.
Returns:
the component at _i in the name. May be null.

lastComponent

public final java.lang.String lastComponent()
Gets the last component of the name.

Specified by:
lastComponent in interface ImmutableName
Returns:
the last component (may be null)

contains

public final boolean contains(ImmutableName _name)
Specified by:
contains in interface ImmutableName
Parameters:
_name - never null.
Returns:
true if _name components are all there in the instance, but not always in the same order

clone

public final java.lang.Object clone()
Get a clone of name.

Specified by:
clone in interface ImmutableName
Overrides:
clone in class java.lang.Object
Returns:
a cloned and no-backed instance of mutable name that may be cast as a Name or an ImmutableName. May be null.
Throws:
java.lang.InternalError - if CloneNotSupportedException

equals

public final boolean equals(java.lang.Object _obj)
Compares the two names.

Specified by:
equals in interface ImmutableName
Overrides:
equals in class java.lang.Object
Parameters:
_obj - the object to compare
Returns:
true if the list of strings is equal - not only identical - even if the two objects are instances of the same class that implements Name (and not only ImmutableName)

hashCode

public final int hashCode()
Specified by:
hashCode in interface ImmutableName
Overrides:
hashCode in class java.lang.Object
Returns:
the hashcode value for this instance of Name. May be null.

compareTo

public final int compareTo(java.lang.Object o)
                    throws java.lang.ClassCastException
Specified by:
compareTo in interface ImmutableName
Specified by:
compareTo in interface java.lang.Comparable
Parameters:
o - Object to compare must be an ImmutableName (true for Name)
Returns:
0 if the names are equals, a negative integer if this Name object is lesser than the argument, and a positive integer if this Name object is greater than the argument. The comparison is based on the Unicode value of each character in each Name component (starting from the first one) and the number of components (negative return if all strings of this Name are equals but with less components, or if the argument is null).
Throws:
java.lang.ClassCastException - - if the specified object's type prevents it from being compared to this current Object

getSerialVersionUID

public final long getSerialVersionUID()
Specified by:
getSerialVersionUID in interface ImmutableName
Returns:
long serial version UID for serialization of the class

toString

public final java.lang.String toString()
Gets a String representation with one leading whitespace and ':: ' at the end, or gets ' null '.

Overrides:
toString in class java.lang.Object
Returns:
String

getNameFromString

public static final Name getNameFromString(java.lang.String _text)
                                    throws BaseError
Gets the name from the string returned by toString(). The toString() method returns a text with one leading and one trailing whitespaces. To handle the user entering of a text, the argument may have more than one whitespace before, and more than two whitespaces after the effective characters, since this method gets off all these whitespaces before the processing.

Parameters:
_text - name, as get through toString()
Returns:
the name. Empty if _text equals " null ".
Throws:
BaseError - if the string argument is null or empty, or if the string does not start with ' ' or is not ended by ':: '.