edu.nrao.sss.catalog
Class CatalogItemGroup<I extends CatalogItem<I>,G extends CatalogItemGroup<I,G,C>,C extends Catalog<I,G,C>>

java.lang.Object
  edu.nrao.sss.catalog.CatalogItemGroup<I,G,C>

All Implemented Interfaces:

Cloneable

Direct Known Subclasses:

SimpleItemGroup

public class CatalogItemGroup<I extends CatalogItem<I>,G extends CatalogItemGroup<I,G,C>,C extends Catalog<I,G,C>>
extends Object
implements Cloneable

A grouping of catalog items. A CatalogItemGroup is normally contained in a Catalog and is a way of collecting together items that have similar traits.

Version Info:

$Revision: 2232 $

$Date: 2009-04-23 13:38:46 -0600 (Thu, 23 Apr 2009) $

$Author: dharland $ (last person to modify)

Since:

2006-10-23

Author:

David M. Harland

Constructor Summary

	CatalogItemGroup() Creates a new group with a default name and that belongs to no catalog.
protected	CatalogItemGroup(C container) Special constructor used only by Catalog for constructing its main group.
	CatalogItemGroup(C container, String nameOfGroup) Creates a new group that belongs to container.

Method Summary

I	add(I newMember) Adds a new member to this group.
I	add(int index, I newMember) Adds a new member to this group at the specified position.
Collection<I>	addAll(Collection<? extends I> newMembers) Adds the collection of newMembers to this group.
Collection<I>	addAll(int index, Collection<? extends I> newMembers) Adds the collection of newMembers to this group at the specified position.
I	addEvenIfEqualToCurrentMember(I newMember) Adds newMember even if this group already has a member to which it is equal.
I	addEvenIfEqualToCurrentMember(int index, I newMember) Adds newMember at the specified position even if this group already has a member to which it is equal.
void	addListener(CatalogItemGroupListener<I,G,C> newListener) Adds newListener to this group's list.
void	clear() Removes all members from this group.
protected boolean	clearlyNotEqualTo(Object o)
G	clone() Returns a group that is a copy of this one.
protected G	cloneAllExceptMembers() Clones this group but does not add any members to the new group.
G	cloneIntoSameCatalog() Clones this group and adds it to the same catalog to which it belongs.
boolean	contains(I member) Returns true if member belongs to this group.
protected void	copyPropertiesFrom(G otherGroup) Copies some properties of otherGroup into this one.
I	decrementIndexOf(I member) Moves member to an index one lower than its current index.
I	decrementIndexOfMemberAt(int index) Moves the member at index to an index of index-minus-one.
boolean	equals(Object o) Returns true if o is equal to this group.
boolean	equalsWithoutRespectToOrder(Object o) Returns true if o is equal to this group in all respects with the possible exception of the ordering of the members.
I	get(int index) Returns the member at the given position.
List<I>	getAll() Returns a list of this group's members.
C	getCatalog() Returns the catalog to which this group belongs, if any.
Long	getId() Returns this group's ID.
protected long	getIdOfUnidentified() Returns a value that represents an undefined ID.
protected List<I>	getInternalMemberList() Returns the internal list of members.
String	getName() Returns the name of this group.
protected boolean	getNameIsLocked() Returns true if the ability to change this group's name is restricted.
List<String>	getNotes() Returns a list of notes about this group.
boolean	hasCatalog() Returns true if this group has a non-null catalog.
int	hashCode() Returns a hash code value for this group.
I	incrementIndexOf(I member) Moves member to an index one higher than its current index.
I	incrementIndexOfMemberAt(int index) Moves the member at index to an index of index-plus-one.
int	indexOf(I member) Returns the index in this group of the first occurrence of member.
boolean	isEmpty() Returns true if this group has no members.
int	lastIndexOf(I member) Returns the index in this group of the last occurrence of member.
I	move(I member, int toIndex) Moves member toIndex.
I	move(int fromIndex, int toIndex) Moves a member fromIndex toIndex.
I	remove(I member) Removes member from this group, if present.
I	remove(int index) Removes the member at index from this group.
Collection<I>	removeAll(Collection<? extends I> unwantedMembers) Removes all elements of unwantedMembers that are contained in this group.
void	removeAllListeners() Removes all listeners from this group.
void	removeListener(CatalogItemGroupListener<I,G,C> listener) Removes listener from this group's list.
boolean	setCatalog(C newCatalog) Sets the catalog to which this group belongs.
protected void	setId(Long id) Sets the ID of this group.
protected void	setInternalMemberList(List<I> replacementList) Replaces the internal member list with replacementList.
void	setName(String newName) Attempts to change the name of this group to newName.
boolean	setNameAndConfirm(String newName) Attempts to set the name of this group and returns true if this group's name was changed.
protected void	simplySetCatalog(C newCatalog) Sets this group's catalog to newCatalog without contacting either the former or new catalog.
int	size() Returns the number of members in this group.
void	sort(Comparator<? super I> comparator) Uses comparator to sort the members of this group.
List<I>	swap(int index1, int index2) Swaps the members at the given positions.
protected void	tellListenersAboutFormerMember(I formerMember, int index)
protected void	tellListenersAboutMovedMember(I member, int fromIndex, int toIndex)
protected void	tellListenersAboutNewMember(I newMember, int index)
String	toString() Returns a text representation of this group.
String	toXml() Returns an XML representation of this group.
void	writeAsXmlTo(Writer writer) Writes an XML representation of this group to writer.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

CatalogItemGroup

public CatalogItemGroup()

Creates a new group with a default name and that belongs to no catalog.

CatalogItemGroup

public CatalogItemGroup(C container,
                        String nameOfGroup)

Creates a new group that belongs to container.

Parameters:

container - the name of the one catalog to which this group belongs. This value may be null.

nameOfGroup - the name of this group. If this value is null, a non-null default name will be used.

CatalogItemGroup

protected CatalogItemGroup(C container)

Special constructor used only by Catalog for constructing its main group.

Method Detail

setId

protected void setId(Long id)

Sets the ID of this group. If id is null, this group's ID ID will be set to an unidentified ID.

Parameters:

id - a new ID for this group.

getIdOfUnidentified

protected long getIdOfUnidentified()

Returns a value that represents an undefined ID. Subclasses may override this method to suit their needs.

getId

public Long getId()

Returns this group's ID.

Returns:

this group's ID.

setName

public void setName(String newName)

Attempts to change the name of this group to newName.

This method exists for the use of frameworks that rely on java-bean naming conventions and set-methods that are of type void. The preferred method for all other clients is setNameAndConfirm(String), which will let the caller know whether or not the change of name was successful. If this method fails to change this group's name it does so silently.

Parameters:

newName - the new name for this group.

See Also:

setNameAndConfirm(String)

setNameAndConfirm

public boolean setNameAndConfirm(String newName)

Attempts to set the name of this group and returns true if this group's name was changed.

Parameters:

newName - the new name for this group.

Returns:

true if the name of this group was changed to newName. Reasons for a return value of false:

1. The name of this group is locked. (This is controlled by the containing catalog, if this group is a member of a catalog.)
2. newName is null.
3. newName is the empty string "".
4. This group's name is already equal to newName.
5. This group belongs to a catalog and another group in the catalog has a name of newName. (The catalog is now enforcing uniqueness of its groups' names.)

getName

public String getName()

Returns the name of this group.

Returns:

the name of this group.

getNameIsLocked

protected boolean getNameIsLocked()

Returns true if the ability to change this group's name is restricted.

getNotes

public List<String> getNotes()

Returns a list of notes about this group. Each note is free-form text with no particular structure.

This method returns the list actually held by this CatalogItemGroup, so any list manipulations may be performed by first fetching the list and then operating on it.

Returns:

a list of notes about this catalog.

setCatalog

public boolean setCatalog(C newCatalog)

Sets the catalog to which this group belongs.

If this group is currently contained in a catalog that is not the same as the newCatalog parameter, the current catalog will be told to remove this group from its collection of groups. If newCatalog is not null, it will be told to add this group to its collection. Finally, this group's catalog will be set to newCatalog, even if it is null.

The current catalog has the right to deny movement of this group to a new catalog. If the request is denied, this group will remain with its current catalog.

Passing this method a newCatalog of null has the effect of disconnecting this group from any catalog.

Parameters:

newCatalog - the catalog to which this group belongs.

Returns:

true if newCatalog is now the catalog for this group. Note that this means if newCatalog is already the catalog of this group, the return value is true.

simplySetCatalog

protected void simplySetCatalog(C newCatalog)

Sets this group's catalog to newCatalog without contacting either the former or new catalog. This method is used only by the Catalog class.

getCatalog

public C getCatalog()

Returns the catalog to which this group belongs, if any.

This group may be one of several that belong to the same catalog. If this group belongs to no catalog, the value returned is null.

Returns:

the catalog to which this group belongs, if any.

See Also:

hasCatalog()

hasCatalog

public boolean hasCatalog()

Returns true if this group has a non-null catalog.

Catalog item groups should normally be contained within, and therefore have a non-null, catalog. However, there are some situations where this method will return false:

1. This group has just been created and its catalog has not yet been set.
2. A client removed this group from its catalog and did not place it in a new catalog.
3. A client explicitly set this group's catalog to null.

Returns:

true if this group has a non-null catalog. Therefore a return value of true means that you can call getCatalog() and know that it will return a non-null object.

add

public I add(I newMember)

Adds a new member to this group.

The new member is added to this group only if it is not null, and this group currently contains no member that is equal to it. (To bypass the equality restriction, use addEvenIfEqualToCurrentMember(CatalogItem)). If this group belongs to a catalog, the catalog is also informed about the new member.

If this group is part of a catalog, and if the catalog has an item that is equal to newMember, then that equivalent item is used in place of newMember as the new member of this group. This ensures that an item copied from one group of a catalog to another group of the same catalog is a single item that is a member of the two groups. The next section shows what happens to this group, its catalog (if it has one), and the value returned by this method in a few situations.

A. This Group Does Not Belong to a Catalog

1. newMember is null or its addition to this group fails¹.
   Nothing is added to this group and the value returned is null.


2. This group contains no members that are equal to newMember.
   newMember is added to this group and returned.


3. This group contains a member that is equal to newMember.
   The member equal to newMember that is already present in this group is returned. Nothing is added to this group.

B. This Group Does Belong to a Catalog

1. newMember is null or its addition to this group or its catalog fails¹.
   Nothing is added to this group or its catalog and the value returned is null.


2. This group and its catalog contain no members that are equal to newMember.
   newMember is added to this group and to its catalog, and is returned.


3. This group contains no members that are equal to newMember, but its catalog does.
   The member equal to newMember that is already present in the catalog is added to this group and returned. Nothing is added to the catalog.


4. This group, and therefore its catalog, contains a member that is equal to newMember.
   The member equal to newMember that is already present in this group and its is returned. Nothing is added to this group or its catalog.

In general, the return value is the newMember parameter. However, this is not always true when this group is part of a catalog. See the description of the returned value, below.

¹With the exception of a programming error within this class or the Catalog class, this is not expected to happen.

Parameters:

newMember - a prospective new member of this group.

Returns:

null, newMember, or an item that is equal to newMember, as outlined in the situations above.

See Also:

addEvenIfEqualToCurrentMember(CatalogItem)

add

public I add(int index,
             I newMember)

Adds a new member to this group at the specified position.

For a full description of the behavior of this method and its return values, see add(CatalogItem).

Parameters:

index - the position at which to insert the new member.

newMember - a prospective new member of this group.

Returns:

the member that was actually added to, or was already a part of, this group.

See Also:

addEvenIfEqualToCurrentMember(int, CatalogItem)

addAll

public Collection<I> addAll(Collection<? extends I> newMembers)

Adds the collection of newMembers to this group. Only non-null candidates that are not already members of this group are added.

Parameters:

newMembers - a collection of prospective new members.

Returns:

a collection of the members actually added to this group.

See Also:

add(CatalogItem)

addAll

public Collection<I> addAll(int index,
                            Collection<? extends I> newMembers)

Adds the collection of newMembers to this group at the specified position. Only non-null candidates that are not already members of this group are added.

Parameters:

index - the position at which to insert the first new member. Subsequent new members are added at successive positions.

newMembers - a collection of prospective new members.

Returns:

a collection of the members actually added to this group.

See Also:

add(CatalogItem)

addEvenIfEqualToCurrentMember

public I addEvenIfEqualToCurrentMember(I newMember)

Adds newMember even if this group already has a member to which it is equal. Contrast this with add(CatalogItem).

The only times newMember is not added to this group are when it is null and when a reference to it is already contained in this group.

Parameters:

newMember - a potential new member for this group.

Returns:

newMember.

addEvenIfEqualToCurrentMember

public I addEvenIfEqualToCurrentMember(int index,
                                       I newMember)

Adds newMember at the specified position even if this group already has a member to which it is equal. Contrast this with add(int, CatalogItem).

The only times newMember is not added to this group are when it is null and when a reference to it is already contained in this group.

Parameters:

index - the position at which to add newMember.

newMember - a potential new member for this group.

Returns:

newMember.

tellListenersAboutNewMember

protected void tellListenersAboutNewMember(I newMember,
                                           int index)

remove

public I remove(I member)

Removes member from this group, if present.

The returned element is either null (if this group had no member equal to member) or is the removed member, which is the first member of this group that is equal to member.

Parameters:

member - the member that is to be removed from this group.

Returns:

the removed element, or null if no element was removed.

remove

public I remove(int index)

Removes the member at index from this group.

Parameters:

index - the index of the member to be removed.

Returns:

the member formerly at index.

Throws:

IndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size()).

removeAll

public Collection<I> removeAll(Collection<? extends I> unwantedMembers)

Removes all elements of unwantedMembers that are contained in this group.

Parameters:

unwantedMembers - the members that are to be removed from this group.

Returns:

the former members that were removed from this group as a result of the call.

clear

public void clear()

Removes all members from this group.

tellListenersAboutFormerMember

protected void tellListenersAboutFormerMember(I formerMember,
                                              int index)

incrementIndexOf

public I incrementIndexOf(I member)

Moves member to an index one higher than its current index. The member will not be moved if it is not in this group, or if it is already in the highest position.

If member is in this group in multiple positions, the instance with the highest index will be moved.

Parameters:

member - the member to be moved.

Returns:

if no movement occurred, null is returned. Otherwise the member that was moved is returned. This will be either member, or an equal member that was already part of this group.

decrementIndexOf

public I decrementIndexOf(I member)

Moves member to an index one lower than its current index. The member will not be moved if it is not in this group, or if it is already in the lowest position.

If member is in this group in multiple positions, the instance with the lowest index will be moved.

Parameters:

member - the member to be moved.

Returns:

if no movement occurred, null is returned. Otherwise the member that was moved is returned. This will be either member, or an equal member that was already part of this group.

incrementIndexOfMemberAt

public I incrementIndexOfMemberAt(int index)

Moves the member at index to an index of index-plus-one. No move will occur if index is out of bounds, or if it is already the highest index of this group.

Parameters:

index - the index of the member to be moved.

Returns:

the member that was moved, or null if no member was moved.

decrementIndexOfMemberAt

public I decrementIndexOfMemberAt(int index)

Moves the member at index to an index of index-minus-one. No move will occur if index is out of bounds, or if it is already the lowest index of this group.

Parameters:

index - the index of the member to be moved.

Returns:

the member that was moved, or null if no member was moved.

swap

public List<I> swap(int index1,
                    int index2)

Swaps the members at the given positions.

If the indices are equal, no action is taken. If one or both of the indices are not in the range [0,size()), the underlying List will throw an exception.

Parameters:

index1 - the position of the one of the members.

index2 - the position of another of the members.

Returns:

a list with the member originally at the lower index followed by the member originally at the higher index. If no swap was made the returned list will be empty.

move

public I move(int fromIndex,
              int toIndex)

Moves a member fromIndex toIndex.

Parameters:

fromIndex - the current index of a member.

toIndex - the new index of that same member.

Returns:

the member that moved, even if it moved back to the same position.

move

public I move(I member,
              int toIndex)

Moves member toIndex.

Parameters:

member - the member to be moved.

toIndex - the new position for member.

Returns:

the member that moved, or null if no movement occurred. Note that the member that moved might be member or, alternatively, a member equal to member, if this group has such a member.

tellListenersAboutMovedMember

protected void tellListenersAboutMovedMember(I member,
                                             int fromIndex,
                                             int toIndex)

sort

public void sort(Comparator<? super I> comparator)

Uses comparator to sort the members of this group.

Parameters:

comparator - used to order this group's members

size

public int size()

Returns the number of members in this group.

Returns:

the number of members in this group.

get

public I get(int index)

Returns the member at the given position.

Parameters:

index - the position of the member to return.

Returns:

the member at index.

getAll

public List<I> getAll()

Returns a list of this group's members.

Note that the returned list is not held internally by this group. This means that any changes made to the returned list will not be reflected in this object. The elements of the list, though, are the actual members of this group, so changes made to them will be reflected in this group (and in all other groups of which those items are members).

Returns:

a list of this group's members. The returned value is guaranteed to be non-null, but it may be an empty list.

getInternalMemberList

protected List<I> getInternalMemberList()

Returns the internal list of members.

setInternalMemberList

protected void setInternalMemberList(List<I> replacementList)

Replaces the internal member list with replacementList. This method is meant solely for use by frameworks (such as JAXB or Hibernate) that rely on getX/setX pairs for persisted properties. It is protected, as opposed to private, so that subclasses can create and annotate methods that call this one.

isEmpty

public boolean isEmpty()

Returns true if this group has no members.

Returns:

true if this group has no members.

contains

public boolean contains(I member)

Returns true if member belongs to this group.

Parameters:

member - a possible member of this group.

Returns:

true if member belongs to this group.

indexOf

public int indexOf(I member)

Returns the index in this group of the first occurrence of member. Indexing is zero-based.

Parameters:

member - the member whose index is sought.

Returns:

the index of the first occurrence of member. If member does not belong to this group, the returned value will be less than zero.

lastIndexOf

public int lastIndexOf(I member)

Returns the index in this group of the last occurrence of member. Indexing is zero-based.

Parameters:

member - the member whose index is sought.

Returns:

the index of the last occurrence of member. If member does not belong to this group, the returned value will be less than zero.

addListener

public void addListener(CatalogItemGroupListener<I,G,C> newListener)

Adds newListener to this group's list.

The listener will be informed whenever:

• A new member is added to this group
• A current member is removed from this group
• A current member is moved from one position in this group to another

Parameters:

newListener - the listener to be added to this group's list.

removeListener

public void removeListener(CatalogItemGroupListener<I,G,C> listener)

Removes listener from this group's list.

Parameters:

listener - the listener to be removed from this group's list.

removeAllListeners

public void removeAllListeners()

Removes all listeners from this group.

toString

public String toString()

Returns a text representation of this group.

Overrides:

toString in class Object

Returns:

a text representation of this group.

toXml

public String toXml()
             throws JAXBException

Returns an XML representation of this group.

Returns:

an XML representation of this group.

Throws:

JAXBException - if anything goes wrong during the conversion to XML.

writeAsXmlTo

public void writeAsXmlTo(Writer writer)
                  throws JAXBException

Writes an XML representation of this group to writer.

Parameters:

writer - the device to which XML is written.

Throws:

JAXBException - if anything goes wrong during the conversion to XML.

cloneIntoSameCatalog

public G cloneIntoSameCatalog()

Clones this group and adds it to the same catalog to which it belongs. If this group belongs to no catalog, this method behaves the same as clone().

Special Notes on Cloning Methodology

1. The clone's ID property will be set to a value that indicates that this group is currently unidentified.
2. The clone will have no listeners.

If anything goes wrong during the cloning procedure, a RuntimeException will be thrown.

Returns:

a clone of this group that belongs to the same catalog.

See Also:

clone()

clone

public G clone()

Returns a group that is a copy of this one. The clone is a deep clone; all the members in the returned group are copies of those in this group.

Special Notes on Cloning Methodology

1. The clone's ID property will be set to a value that indicates that this group is currently unidentified.
2. The clone will belong to no catalog. That is, its catalog property will be null.
3. The clone will have no listeners.

If anything goes wrong during the cloning procedure, a RuntimeException will be thrown.

Overrides:

clone in class Object

See Also:

cloneIntoSameCatalog()

cloneAllExceptMembers

protected G cloneAllExceptMembers()

Clones this group but does not add any members to the new group.

Returns:

a partial clone of this group. The returned clone has no members.

copyPropertiesFrom

protected void copyPropertiesFrom(G otherGroup)

Copies some properties of otherGroup into this one.

This method is used by the catalog's clone method to help copy its main group, which is not created via the normal cloning process. Subclasses should override this method and call super.copyPropertiesFrom(otherGroup). Failure to do so will result in some properties of a cloned catalog from matching that of the original.

What is not copied:

• id
• catalog reference
• listeners
• items

Subclasses should copy only those new properties that it creates. This list will be similar, if not identical, to the properties copied in the subclass's clone method.

The fact that this method has become necessary probably means that the way we're handling setup of a catalog's main group could probably be done better. One reason we don't just clone the main group is the main group uses a special non-public constructor. A reworking of the main group creation and cloning code should be done later on.

Parameters:

otherGroup - a source of property values.

equalsWithoutRespectToOrder

public boolean equalsWithoutRespectToOrder(Object o)

Returns true if o is equal to this group in all respects with the possible exception of the ordering of the members.

equals

public boolean equals(Object o)

Returns true if o is equal to this group.

Overrides:

equals in class Object

clearlyNotEqualTo

protected boolean clearlyNotEqualTo(Object o)

hashCode

public int hashCode()

Returns a hash code value for this group.

Overrides:

hashCode in class Object