edu.isi.pegasus.planner.catalog.replica

## Class ReplicaCatalogEntry

- java.lang.Object
- - edu.isi.pegasus.planner.catalog.replica.ReplicaCatalogEntry

All Implemented Interfaces:
  CatalogEntry, java.lang.Cloneable

    public class ReplicaCatalogEntry
    extends java.lang.Object
    implements CatalogEntry, java.lang.Cloneable

The entry is a high-level logical structure representing the physical filename, the site handle, and optional attributes related to the PFN as one entity.

The resource handle is the most frequently used attribute. In reality, the resource handle may be a relational attribute of the mapping relation between an LFN and a PFN - there is disagreement among the developers on this issue. For simplicity purposes, it appears to be sufficient to make the resource handle a regular PFN attribute.

Version:
  $Revision$
Author:
  Jens-S. Vöckler, Karan Vahi

### Field Summary

Fields
`private java.util.Map` `m_attributeMap` Any optional attributes associated with the PFN.
`private java.lang.String` `m_pfn` The physical filename.
`static java.lang.String` `RESOURCE_HANDLE` The (reserved) attribute name used for the resource handle.

### Constructor Summary

Constructors
Constructor and Description
`ReplicaCatalogEntry()` Default constructor for arrays.
`ReplicaCatalogEntry(java.lang.String pfn)` Convenience constructor initializes the PFN.
`ReplicaCatalogEntry(java.lang.String pfn, java.util.Map attributes)` Standard constructor initializes the PFN and arbitrary attributes.
`ReplicaCatalogEntry(java.lang.String pfn, java.lang.String handle)` Convenience constructor initializes the PFN and the resource handle.

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`void` `addAttribute(java.util.Map attributes)` Adds attributes to the existing attributes.
`void` `addAttribute(java.lang.String key, java.lang.Object value)` Adds an attribute to the set of attributes.
`java.lang.Object` `clone()`
`boolean` `equals(java.lang.Object obj)` Matches two ReplicaCatalogEntry objects.
`java.lang.Object` `getAttribute(java.lang.String key)` Obtains the attribute value for a given key.
`int` `getAttributeCount()` Counts the number of attributes known for the PFN.
`java.util.Iterator` `getAttributeIterator()` Provides an iterator to traverse the attributes by their keys.
`java.lang.String` `getPFN()` Accessor: Obtains the PFN portion from this entry.
`java.lang.String` `getResourceHandle()` Obtains the resource handle from the attributes map.
`boolean` `hasAttribute(java.lang.String key)` Checks for the existence of an attribute key.
`boolean` `merge(ReplicaCatalogEntry rce, boolean overwrite)` Merges the attribute maps in a controlled fashion.
`static ReplicaCatalogEntry` `merge(ReplicaCatalogEntry a, ReplicaCatalogEntry b, boolean overwrite)` Merges the attribute maps of two entries in a controlled fashion.
`void` `removeAllAttribute()` Removes all attributes associated with a PFN.
`java.lang.Object` `removeAttribute(java.lang.String name)` Removes a specific attribute.
`void` `setAttribute(java.util.Map attributes)` Replaces all existing attributes with new attributes.
`void` `setAttribute(java.lang.String key, java.lang.Object value)` Adds a new or overwrites an existing attribute.
`void` `setPFN(java.lang.String pfn)` Accessor: Sets a new PFN to remember.
`void` `setResourceHandle(java.lang.String handle)` Sets a new resource handle to remember as PFN attribute.
`java.lang.String` `toString()` Converts the contents into a string.

### Methods inherited from class java.lang.Object

`finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

### Field Detail

#### RESOURCE_HANDLE

    public static final java.lang.String RESOURCE_HANDLE

The (reserved) attribute name used for the resource handle.

See Also:
  Constant Field Values

#### m_pfn

    private java.lang.String m_pfn

The physical filename.

#### m_attributeMap

    private java.util.Map m_attributeMap

Any optional attributes associated with the PFN.

### Constructor Detail

#### ReplicaCatalogEntry

    public ReplicaCatalogEntry()

Default constructor for arrays. The PFN is initialized to `null</null>, and thus must be explicitly set later. The map of attributes associated with the PFN is initialized to be empty. Thus, no resource handle is available.`

#### ReplicaCatalogEntry

    public ReplicaCatalogEntry(java.lang.String pfn)

Convenience constructor initializes the PFN. The map of attributes is initialized to be empty. Thus, no resource handle is avaiable.

Parameters:
  `pfn` - is the PFN to remember.

#### ReplicaCatalogEntry

    public ReplicaCatalogEntry(java.lang.String pfn,
                               java.lang.String handle)

Convenience constructor initializes the PFN and the resource handle. The resource handle is stored as regular PFN attribute.

Parameters:
  `pfn` - is the PFN to remember.
  `handle` - is the resource handle to remember.

#### ReplicaCatalogEntry

    public ReplicaCatalogEntry(java.lang.String pfn,
                               java.util.Map attributes)

Standard constructor initializes the PFN and arbitrary attributes.

Parameters:
  `pfn` - is the PFN to remember.
  `attributes` - is a map of arbitrary attributes related to the PFN.

### Method Detail

#### addAttribute

    public void addAttribute(java.lang.String key,
                             java.lang.Object value)

Adds an attribute to the set of attributes. Note, this is identical to the `setAttribute( String, Object )` method of the same signature.

Parameters:
  `key` - is the key denoting an attribute.
  `value` - is a value object to store.

#### addAttribute

    public void addAttribute(java.util.Map attributes)

Adds attributes to the existing attributes.

Parameters:
  `attributes` - is a map of attributes to add.
See Also:
  `setAttribute(Map)`, `Map.putAll( Map )`

#### getAttribute

    public java.lang.Object getAttribute(java.lang.String key)

Obtains the attribute value for a given key.

Parameters:
  `key` - is the key to look up
Returns:
  the object stored as value, may be null.
See Also:
  `Map.get( Object )`

#### hasAttribute

    public boolean hasAttribute(java.lang.String key)

Checks for the existence of an attribute key.

Parameters:
  `key` - is the key to look up
Returns:
  true if the key is known, false otherwise.

#### getAttributeCount

    public int getAttributeCount()

Counts the number of attributes known for the PFN.

Returns:
  number of attributes, may be zero.
See Also:
  `Map.size()`

#### getAttributeIterator

    public java.util.Iterator getAttributeIterator()

Provides an iterator to traverse the attributes by their keys.

Returns:
  an iterator over the keys to walk the attribute list.

#### merge

    public static ReplicaCatalogEntry merge(ReplicaCatalogEntry a,
                                            ReplicaCatalogEntry b,
                                            boolean overwrite)

Merges the attribute maps of two entries in a controlled fashion. Entries are only merged with another entry, if the physical filenames match.

Parameters:
  `a` - is one replica catalog entry to merge.
  `b` - is the other replica catalog entry to merge.
  `overwrite` - resolves intersections. If true, uses rce's attribute to remain, if false, the original attribute remains.
Returns:
  the merged entry, if the PFNs matched, or `null` if the PFN mismatched.

#### merge

    public boolean merge(ReplicaCatalogEntry rce,
                         boolean overwrite)

Merges the attribute maps in a controlled fashion. An entry is only merged with another entry, if the physical filenames match.

Parameters:
  `rce` - is another replica catalog entry to merge with.
  `overwrite` - resolves intersections. If true, uses rce's attribute to remain, if false, the original attribute remains.
Returns:
  true if a merge was attempted, false if the PFNs did not match.

#### removeAllAttribute

    public void removeAllAttribute()

Removes all attributes associated with a PFN.

See Also:
  `removeAttribute( String )`

#### removeAttribute

    public java.lang.Object removeAttribute(java.lang.String name)

Removes a specific attribute.

Parameters:
  `name` - is the name of the attribute to remove.
Returns:
  the value object that was removed, or `null`, if the key was not in the map.
See Also:
  `removeAllAttribute()`

#### setAttribute

    public void setAttribute(java.lang.String key,
                             java.lang.Object value)

Adds a new or overwrites an existing attribute. Note, this is identical to the `addAttribute( String, Object)` method of the same signature.

Parameters:
  `key` - is the name of the attribute
  `value` - is the value object associated with the attribute.

#### setAttribute

    public void setAttribute(java.util.Map attributes)

Replaces all existing attributes with new attributes. Existing attributes are removed before attempting a shallow copy of the new attributes.

Parameters:
  `attributes` - is the map of new attributes to remember.
See Also:
  `addAttribute(Map)`

#### getResourceHandle

    public java.lang.String getResourceHandle()

Obtains the resource handle from the attributes map. This is a convenience method. Internally, the PFN attribute map is queried for the value of the resource handle.

Returns:
  the resource handle, or `null` if unset.
See Also:
  `setResourceHandle( String )`

#### setResourceHandle

    public void setResourceHandle(java.lang.String handle)

Sets a new resource handle to remember as PFN attribute. This is a convenience method. Internally, the PFN attribute map is changed to remember the new resource handle.

Parameters:
  `handle` - is the new resource handle.
See Also:
  `getResourceHandle()`

#### getPFN

    public java.lang.String getPFN()

Accessor: Obtains the PFN portion from this entry.

Returns:
  the physical filename, or `null` if unset.
See Also:
  `setPFN( String )`

#### setPFN

    public void setPFN(java.lang.String pfn)

Accessor: Sets a new PFN to remember.

Parameters:
  `pfn` - is a new physical filename.
See Also:
  `getPFN()`

#### toString

    public java.lang.String toString()

Converts the contents into a string.

Overrides:
  `toString` in class `java.lang.Object`
Returns:
  a textual representation of the item content.

#### equals

    public boolean equals(java.lang.Object obj)

Matches two ReplicaCatalogEntry objects. The primary key in this case is the pfn and all the attributes.

Overrides:
  `equals` in class `java.lang.Object`
Returns:
  true if the pfn and all the attributes match, false otherwise.

#### clone

    public java.lang.Object clone()
                           throws java.lang.CloneNotSupportedException

Overrides:
  `clone` in class `java.lang.Object`
Throws:
  `java.lang.CloneNotSupportedException`