edu.nrao.sss.model.source
Class SourceGroup

java.lang.Object
  edu.nrao.sss.catalog.CatalogItemGroup<SourceCatalogEntry,SourceGroup,SourceCatalog>
      edu.nrao.sss.model.source.SourceGroup

All Implemented Interfaces:

SourceProvider, Identifiable, Cloneable

public class SourceGroup
extends CatalogItemGroup<SourceCatalogEntry,SourceGroup,SourceCatalog>
implements Identifiable, Cloneable, SourceProvider

A collection of Sources and SourceLookupTables. A SourceGroup is normally contained in a SourceCatalog and is a way of categorizing sources that have similar traits.

Version Info:

$Revision: 2313 $

$Date: 2009-05-20 15:00:52 -0600 (Wed, 20 May 2009) $

$Author: btruitt $

Since:

2006-09-15

Author:

David M. Harland

Field Summary

Fields inherited from interface edu.nrao.sss.util.Identifiable

UNIDENTIFIED

Constructor Summary

SourceGroup()
Creates a new group that has a default name and that belongs to no catalog.

SourceGroup(SourceCatalog container, String nameOfGroup)
Creates a new group that belongs to container.

Method Summary

SourceCatalogEntry	add(SourceCatalogEntry newMember) Adds a new member to this source group.
SourceGroup	clone() Returns a source group that is a copy of this one.
boolean	equals(Object o) Returns true if o is equal to this source group.
Source	findSourceById(long id) Returns the Source with the given id, if any.
List<Source>	findSourceByName(String name) Returns the Source(s) with the given name, if any.
SourceLookupTable	findSourceTableById(long id) Returns the SourceLookupTable with the given id, if any.
List<SourceLookupTable>	findSourceTableByName(String name) Returns the SourceLookupTable(s) with the given name, if any.
static SourceGroup	fromXml(Reader reader) Creates a new group based on the XML data read from reader.
static SourceGroup	fromXml(String xmlFile) Creates a new group from the XML data in the given file.
protected long	getIdOfUnidentified() Returns Identifiable.UNIDENTIFIED.
static Comparator<SourceGroup>	getNameComparator() Returns a comparator that uses the name of the source groups sent to it.
List<Source>	getSources() Returns a set of all sources held by this group.
List<Source>	getSources(Filter<Source> filter) Returns a set of all sources in this group that can pass through filter.
List<SourceLookupTable>	getSourceTables() Returns a set of all source lookup tables held by this group.
int	hashCode() Returns a hash code value for this group.
SourceCatalogEntry	remove(int index)
SourceCatalogEntry	remove(SourceCatalogEntry member)
List<Source>	removeAllSources() Removes all sources from this group.
List<SourceLookupTable>	removeAllSourceTables() Removes all source tables from this group.
boolean	setCatalog(SourceCatalog newCatalog) Sets the catalog to which this source group belongs.
protected void	simplySetCatalog(SourceCatalog newCatalog) Sets this group's catalog to newCatalog without contacting either the former or new catalog.

Methods inherited from class edu.nrao.sss.catalog.CatalogItemGroup

add, addAll, addAll, addEvenIfEqualToCurrentMember, addEvenIfEqualToCurrentMember, addListener, clear, clearlyNotEqualTo, cloneAllExceptMembers, cloneIntoSameCatalog, contains, copyPropertiesFrom, decrementIndexOf, decrementIndexOfMemberAt, equalsWithoutRespectToOrder, get, getAll, getCatalog, getId, getInternalMemberList, getName, getNameIsLocked, getNotes, hasCatalog, incrementIndexOf, incrementIndexOfMemberAt, indexOf, isEmpty, lastIndexOf, move, move, removeAll, removeAllListeners, removeListener, setId, setInternalMemberList, setName, setNameAndConfirm, size, sort, swap, tellListenersAboutFormerMember, tellListenersAboutMovedMember, tellListenersAboutNewMember, toString, toXml, writeAsXmlTo

Methods inherited from class java.lang.Object

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

Methods inherited from interface edu.nrao.sss.util.Identifiable

getId

Constructor Detail

SourceGroup

public SourceGroup()

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

SourceGroup

public SourceGroup(SourceCatalog 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.

Method Detail

getIdOfUnidentified

protected long getIdOfUnidentified()

Returns Identifiable.UNIDENTIFIED.

Overrides:

getIdOfUnidentified in class CatalogItemGroup<SourceCatalogEntry,SourceGroup,SourceCatalog>

setCatalog

public boolean setCatalog(SourceCatalog newCatalog)

Sets the catalog to which this source group belongs. See CatalogItemGroup.setCatalog(edu.nrao.sss.catalog.Catalog) for more details.

Overrides:

setCatalog in class CatalogItemGroup<SourceCatalogEntry,SourceGroup,SourceCatalog>

Parameters:

newCatalog - the catalog to which this group belongs.

Returns:

true if newCatalog is the new 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(SourceCatalog newCatalog)

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

Overrides:

simplySetCatalog in class CatalogItemGroup<SourceCatalogEntry,SourceGroup,SourceCatalog>

add

public SourceCatalogEntry add(SourceCatalogEntry newMember)

Adds a new member to this source group.

If this group is not part of a catalog, and if the newMember is accepted into the group, this group will hold a reference to newMember. However, if this group is part of a catalog, and if the catalog holds an entry that is equal to newMember, this group will hold a reference to the equivalent entry in the catalog.

Overrides:

add in class CatalogItemGroup<SourceCatalogEntry,SourceGroup,SourceCatalog>

Parameters:

newMember - a new member of this source group.

Returns:

true if this group changed as a result of the call. Reasons for a return value of false:

1. newMember is null
2. newMember is already a member of this group

remove

public SourceCatalogEntry remove(SourceCatalogEntry member)

Overrides:

remove in class CatalogItemGroup<SourceCatalogEntry,SourceGroup,SourceCatalog>

remove

public SourceCatalogEntry remove(int index)

Overrides:

remove in class CatalogItemGroup<SourceCatalogEntry,SourceGroup,SourceCatalog>

removeAllSources

public List<Source> removeAllSources()

Removes all sources from this group.

Returns:

a list of all sources that were removed from this group.

removeAllSourceTables

public List<SourceLookupTable> removeAllSourceTables()

Removes all source tables from this group.

Returns:

a list of all source tables that were removed from this group.

getSources

public List<Source> getSources()
                        throws RepositoryException

Returns a set of all sources held by this group.

If this group is contained in a catalog, it may have references to sources that are not members of this group. This happens when the group contains SourceLookupTables; the sources in those tables need not be in this group. In this situation, those sources are not present in the returned set. Only sources held directly by this group are returned.

Note that the returned set is not held internally by this gorup. This means that any changes made to the set after calling this method will not be reflected in this object. The sources themselves, however, are the actual sources held in this group, so changes made to them will be reflected in this object. Furthermore, if this group is part of a catalog, then the catalog, and perhaps other groups, will be referring to these same source instances, so changes made to the sources in the returned set will be reflected in all those other containers.

Specified by:

getSources in interface SourceProvider

Returns:

a set of all sources held by this group.

Throws:

RepositoryException - under no conditions.

See Also:

CatalogItemGroup.getAll(), getSourceTables(), #getSources(SourceFilter)

getSources

public List<Source> getSources(Filter<Source> filter)
                        throws RepositoryException

Returns a set of all sources in this group that can pass through filter. If filter is null, it will be treated as a wide-open filter, allowing all sources to pass.

See getSources() for details about the returned set.

Specified by:

getSources in interface SourceProvider

Parameters:

filter - a filter to apply to all sources in this group. Only those sources that may pass through filter will be in the returned set.

Returns:

a set of all sources in this group that can pass through filter.

Throws:

RepositoryException - under no conditions.

See Also:

CatalogItemGroup.getAll(), getSources(), getSourceTables()

getSourceTables

public List<SourceLookupTable> getSourceTables()
                                        throws RepositoryException

Returns a set of all source lookup tables held by this group.

Note that the returned set is not held internally by this gorup. This means that any changes made to the set after calling this method will not be reflected in this object. The tables themselves, however, are the actual tables held in this group, so changes made to them will be reflected in this object. Furthermore, if this group is part of a catalog, then the catalog, and perhaps other groups, will be referring to these same table instances, so changes made to the tables in the returned set will be reflected in all those other containers.

Specified by:

getSourceTables in interface SourceProvider

Returns:

a set of all source lookup tables held by this group.

Throws:

RepositoryException - under no conditions.

See Also:

CatalogItemGroup.getAll(), getSources()

findSourceById

public Source findSourceById(long id)
                      throws RepositoryException

Description copied from interface: SourceProvider

Returns the Source with the given id, if any.

If this provider holds no Source with an ID of id, null is returned.

Specified by:

findSourceById in interface SourceProvider

Parameters:

id - the identifier (primary key) for a Source in this repository.

Returns:

The Source with the given id, or null, if this provider holds no such Source.

Throws:

RepositoryException - if anything goes wrong while trying to fetch sources from this provider.

findSourceTableById

public SourceLookupTable findSourceTableById(long id)
                                      throws RepositoryException

Description copied from interface: SourceProvider

Returns the SourceLookupTable with the given id, if any.

If this provider holds no SourceLookupTable with an ID of id, null is returned.

Specified by:

findSourceTableById in interface SourceProvider

Parameters:

id - the identifier (primary key) for a SourceLookupTable in this repository.

Returns:

The SourceLookupTable with the given id, or null, if this provider holds no such SourceLookupTable.

Throws:

RepositoryException - if anything goes wrong while trying to fetch source tables from this provider.

findSourceByName

public List<Source> findSourceByName(String name)
                              throws RepositoryException

Description copied from interface: SourceProvider

Returns the Source(s) with the given name, if any.

Ideally, the returned list will contain only one source. However, since the name is not usually used as a primary key to a source, it is possible that the returned list may contain more than one source. If this provider holds no Source with a name of name, the returned list will be empty.

Specified by:

findSourceByName in interface SourceProvider

Parameters:

name - the name of a Source requested from this provider.

Returns:

The Sources with the given name, or null, if this provider holds no such Source.

Throws:

RepositoryException - if anything goes wrong while trying to fetch sources from this provider.

findSourceTableByName

public List<SourceLookupTable> findSourceTableByName(String name)
                                              throws RepositoryException

Description copied from interface: SourceProvider

Returns the SourceLookupTable(s) with the given name, if any.

Ideally, the returned list will contain only one table. However, since the name is not usually used as a primary key to a table, it is possible that the returned list may contain more than one table. If this provider holds no SourceLookupTable with a name of name, the returned list will be empty.

Specified by:

findSourceTableByName in interface SourceProvider

Parameters:

name - the name of a SourceLookupTable requested from this provider.

Returns:

The SourceLookupTables with the given name, or null, if this provider holds no such table.

Throws:

RepositoryException - if anything goes wrong while trying to fetch tables from this provider.

fromXml

public static SourceGroup fromXml(String xmlFile)
                           throws JAXBException,
                                  XMLStreamException,
                                  FileNotFoundException

Creates a new group from the XML data in the given file.

Parameters:

xmlFile - the name of an XML file. This method will attempt to locate the file by using Class.getResource(String).

Returns:

a new group from the XML data in the given file.

Throws:

FileNotFoundException - if the XML file cannot be found.

JAXBException - if the schema file used (if any) is malformed, if the XML file cannot be read, or if the XML file is not schema-valid.

XMLStreamException - if there is a problem opening the XML file, if the XML is not well-formed, or for some other "unexpected processing conditions".

fromXml

public static SourceGroup fromXml(Reader reader)
                           throws JAXBException,
                                  XMLStreamException

Creates a new group based on the XML data read from reader.

Parameters:

reader - the source of the XML data. If this value is null, null is returned.

Returns:

a new group based on the XML data read from reader.

Throws:

XMLStreamException - if the XML is not well-formed, or for some other "unexpected processing conditions".

JAXBException - if anything else goes wrong during the transformation.

getNameComparator

public static Comparator<SourceGroup> getNameComparator()

Returns a comparator that uses the name of the source groups sent to it. This comparator treats groups named "DEC +/-##" and "RA ##" as special cases, treating them as coming after all other group names.

Returns:

a comparator for sorting source groups by name, with special treatment for RA and DEC groups.

clone

public SourceGroup clone()

Returns a source 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 Identifiable.UNIDENTIFIED.
2. The clone will belong to no catalog. That is, its catalog property will be null.
3. Any tables that refer to sources that are not in this group will be cloned into the returned group, and clones of the missing sources will be added to the returned group.

Overrides:

clone in class CatalogItemGroup<SourceCatalogEntry,SourceGroup,SourceCatalog>

See Also:

CatalogItemGroup.cloneIntoSameCatalog()

equals

public boolean equals(Object o)

Returns true if o is equal to this source group.

In addition to having the same name, the two groups must have the same number of members, and for every member of this group their must be exactly one equal member in o.

Ordering of Members
The members of the two groups do not have to be in the same order. However, the sources in each group must be in the same position relative to all other sources in the group. The same is true of the tables. Example:

   This Group       Group o
   ----------       -------
   source1          source1
   tableA           source2
   source2          source3
   source3          tableA
   tableB           tableB

The two groups above would be equal because their sources are in the same order, relative only to the other sources, and the tables are also in the same relative order.

Overrides:

equals in class CatalogItemGroup<SourceCatalogEntry,SourceGroup,SourceCatalog>

hashCode

public int hashCode()

Returns a hash code value for this group.

Overrides:

hashCode in class CatalogItemGroup<SourceCatalogEntry,SourceGroup,SourceCatalog>