edu.nrao.sss.model.source
Class SourceCatalog

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

All Implemented Interfaces:

CatalogItemGroupListener<SourceCatalogEntry,SourceGroup,SourceCatalog>, SourceProvider, UserAccountable, Identifiable, Cloneable

public class SourceCatalog
extends Catalog<SourceCatalogEntry,SourceGroup,SourceCatalog>
implements Identifiable, UserAccountable, SourceProvider

A catalog of Sources.

Each entry in a catalog is either a Source or SourceLookupTable. This catalog also supports the notion of SourceGroups, which serve to associate sources with similar traits with one another.

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

Fields inherited from interface edu.nrao.sss.model.UserAccountable

NULL_USER_ID

Constructor Summary

SourceCatalog()
Creates a new catalog with a default name.

SourceCatalog(String nameOfCatalog)
Creates a new catalog with the given name.

Method Summary

SourceCatalogEntry	addItem(SourceCatalogEntry newItem) Adds a new entry to this catalog.
void	clearId() Resets this catalog's ID, and the IDs of all its contents, to a value that represents the unidentified state.
SourceCatalog	clone()
SourceGroup	createGroup()
protected SourceGroup	createMainGroup()
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 SourceCatalog	fromXml(Reader reader) Creates a new catalog based on the XML data read from reader.
static SourceCatalog	fromXml(String xmlFile) Creates a new catalog from the XML data in the given file.
Long	getCreatedBy() Returns the ID of the user who created this object.
Date	getCreatedOn() Returns the date on which this object was created.
protected long	getIdOfUnidentified() Returns Identifiable.UNIDENTIFIED.
Long	getLastUpdatedBy() Returns the ID of the user who most recently updated this object.
Date	getLastUpdatedOn() Returns the most recent date on which this object was updated.
Long	getOwner() Returns the ID of the user who owns this catalog.
List<Source>	getSources() Returns a list of all sources held by this provider.
List<Source>	getSources(Filter<Source> filter) Returns a list of sources held this provider that can pass through filter.
List<SourceLookupTable>	getSourceTables() Returns a list of all source lookup tables held by this provider.
List<SourceGroup>	makeDeclinationGroups() Returns a list of source groups based on the declinations of the sources in this catalog.
List<SourceGroup>	makeRightAscensionGroups() Returns a list of source groups based on the right ascensions of the sources in this catalog.
SourceCatalogEntry	removeItem(int index)
SourceCatalogEntry	removeItem(SourceCatalogEntry entry)
void	setCreatedBy(Long userId) Sets the ID of the user who created this object.
void	setCreatedOn(Date d) Sets the date on which this object was created.
void	setLastUpdatedBy(Long userId) Sets the ID of the user who most recently updated this object.
void	setLastUpdatedOn(Date d) Sets the date on which this object was most recently updated.
void	setOwner(Long userId) Sets the ID of the user who owns this catalog.
String	toXml() Returns an XML representation of this catalog.
void	updateRaAndDecGroups() Updates this catalog with a new collection of right ascension and declination groups.
void	writeAsXmlTo(Writer writer) Writes an XML representation of this catalog to writer.

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

addGroup, addGroup, addGroups, addGroups, addItem, addItemEvenIfEqualToCurrentItem, addItemEvenIfEqualToCurrentItem, addItems, addItems, addListener, clear, contains, containsGroupNamed, decrementIndexOfGroup, decrementIndexOfGroupAt, decrementIndexOfItem, decrementIndexOfItemAt, equals, getGroup, getGroup, getGroups, getGroupsThatContain, getId, getInternalGroupList, getInternalItemList, getItem, getItems, getName, getNotes, getReservedGroupName, hashCode, incrementIndexOfGroup, incrementIndexOfGroupAt, incrementIndexOfItem, incrementIndexOfItemAt, indexOf, lastIndexOf, memberAdded, memberMoved, memberRemoved, memberReplaced, membersSorted, moveGroup, moveGroup, moveItem, moveItem, removeAllGroups, removeAllItems, removeAllListeners, removeGroup, removeGroup, removeListener, setId, setInternalGroupList, setInternalItemList, setName, setReservedGroupName, size, sort, sortGroups, swapGroups, swapItems, tellListenersAboutFormerGroup, tellListenersAboutMovedGroup, tellListenersAboutNewGroup, toGroup, toString

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

SourceCatalog

public SourceCatalog()

Creates a new catalog with a default name.

SourceCatalog

public SourceCatalog(String nameOfCatalog)

Creates a new catalog with the given name.

Parameters:

nameOfCatalog - the name of this catalog. If this value is null, this catalog will be given a default name.

Method Detail

getIdOfUnidentified

protected long getIdOfUnidentified()

Returns Identifiable.UNIDENTIFIED.

Overrides:

getIdOfUnidentified in class Catalog<SourceCatalogEntry,SourceGroup,SourceCatalog>

createMainGroup

protected SourceGroup createMainGroup()

Specified by:

createMainGroup in class Catalog<SourceCatalogEntry,SourceGroup,SourceCatalog>

createGroup

public SourceGroup createGroup()

Specified by:

createGroup in class Catalog<SourceCatalogEntry,SourceGroup,SourceCatalog>

clearId

public void clearId()

Resets this catalog's ID, and the IDs of all its contents, to a value that represents the unidentified state.

This method is useful for preparing a catalog for storage in a database. The ID property (as of now, though this may change in the future) is used by our persistence mechanism to identify objects. If you are persisting this catalog for the first time, you may need to call this method before performing a save. This is especially true if you have created this source from XML, as the XML unmarshalling brings along the ID property.

Overrides:

clearId in class Catalog<SourceCatalogEntry,SourceGroup,SourceCatalog>

addItem

public SourceCatalogEntry addItem(SourceCatalogEntry newItem)

Adds a new entry to this catalog.

Overrides:

addItem in class Catalog<SourceCatalogEntry,SourceGroup,SourceCatalog>

Parameters:

newItem - a new entry for this catalog.

Returns:

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

1. newEntry is null
2. newEntry is already contained in this catalog

removeItem

public SourceCatalogEntry removeItem(SourceCatalogEntry entry)

Overrides:

removeItem in class Catalog<SourceCatalogEntry,SourceGroup,SourceCatalog>

removeItem

public SourceCatalogEntry removeItem(int index)

Overrides:

removeItem in class Catalog<SourceCatalogEntry,SourceGroup,SourceCatalog>

makeRightAscensionGroups

public List<SourceGroup> makeRightAscensionGroups()

Returns a list of source groups based on the right ascensions of the sources in this catalog.

Only those groups that have sources in the appropriate RA range are held by the returned list. Each group holds one hour-angle of sources. This method does not automatically add the returned groups to this catalog.

Returns:

a list of source groups based on the right ascensions of the sources in this catalog.

See Also:

makeDeclinationGroups(), updateRaAndDecGroups()

makeDeclinationGroups

public List<SourceGroup> makeDeclinationGroups()

Returns a list of source groups based on the declinations of the sources in this catalog.

Only those groups that have sources in the appropriate declination range are held by the returned list. Each group holds a declination range of ten degrees. This method does not automatically add the returned groups to this catalog.

Returns:

a list of source groups based on the declinations of the sources in this catalog.

See Also:

makeRightAscensionGroups(), updateRaAndDecGroups()

updateRaAndDecGroups

public void updateRaAndDecGroups()

Updates this catalog with a new collection of right ascension and declination groups.

This method is thorough, but not efficient. It works by creating brand new RA and Dec groups, removing the current RA and Dec groups (if any), and then adding the new groups. If you want to make RA and Dec groups for the first time, if you are adding several sources at once, or if you suspect that the sources' positions may have changed, calling this method is probably the right thing to do. If you are adding just one new source, though, and if you know its RA and Dec, it could be more efficient to add it directly to the RA group and Dec group to which it belongs on your own.

See Also:

makeDeclinationGroups(), makeRightAscensionGroups()

getSources

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

Description copied from interface: SourceProvider

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

Specified by:

getSources in interface SourceProvider

Parameters:

filter - the filter through which a source must pass in order to be included in the returned set.

Returns:

a list of sources that can pass through filter.

Throws:

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

getSources

public List<Source> getSources()
                        throws RepositoryException

Description copied from interface: SourceProvider

Returns a list of all sources held by this provider.

Specified by:

getSources in interface SourceProvider

Returns:

a list of all sources held by this provider. If the provider has no sources the returned list will be empty.

Throws:

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

getSourceTables

public List<SourceLookupTable> getSourceTables()
                                        throws RepositoryException

Description copied from interface: SourceProvider

Returns a list of all source lookup tables held by this provider.

Specified by:

getSourceTables in interface SourceProvider

Returns:

a list of all tables held by this provider. If the provider has no tables the returned list will be empty.

Throws:

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

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.

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.

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.

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.

setOwner

public void setOwner(Long userId)

Sets the ID of the user who owns this catalog.

Parameters:

userId - the ID of the user who owns this catalog. If this value is null it will be replaced with UserAccountable.NULL_USER_ID.

setCreatedBy

public void setCreatedBy(Long userId)

Description copied from interface: UserAccountable

Sets the ID of the user who created this object.

If userId is null, this object will be updated not with null but with UserAccountable.NULL_USER_ID instead.

Specified by:

setCreatedBy in interface UserAccountable

Parameters:

userId - the ID of the user who most recently updated this object.

setCreatedOn

public void setCreatedOn(Date d)

Description copied from interface: UserAccountable

Sets the date on which this object was created.

If d is null it will be ignored and this method will do nothing.

Specified by:

setCreatedOn in interface UserAccountable

Parameters:

d - the date on which this object was created.

setLastUpdatedBy

public void setLastUpdatedBy(Long userId)

Description copied from interface: UserAccountable

Sets the ID of the user who most recently updated this object.

If userId is null, this object will be updated not with null but with UserAccountable.NULL_USER_ID instead.

Specified by:

setLastUpdatedBy in interface UserAccountable

Parameters:

userId - the ID of the user who most recently updated this object.

setLastUpdatedOn

public void setLastUpdatedOn(Date d)

Description copied from interface: UserAccountable

Sets the date on which this object was most recently updated.

If d is null it will be ignored and this method will do nothing.

Specified by:

setLastUpdatedOn in interface UserAccountable

Parameters:

d - the date on which this object was most recently updated.

getOwner

public Long getOwner()

Returns the ID of the user who owns this catalog.

Returns:

the ID of the user who owns this catalog.

getCreatedBy

public Long getCreatedBy()

Description copied from interface: UserAccountable

Returns the ID of the user who created this object.

If this object does not know the identity of the user who created it, the returned ID will be UserAccountable.NULL_USER_ID.

Specified by:

getCreatedBy in interface UserAccountable

Returns:

the ID of the user who created this object.

getCreatedOn

public Date getCreatedOn()

Description copied from interface: UserAccountable

Returns the date on which this object was created.

Specified by:

getCreatedOn in interface UserAccountable

Returns:

the date on which this object was created.

getLastUpdatedBy

public Long getLastUpdatedBy()

Description copied from interface: UserAccountable

Returns the ID of the user who most recently updated this object.

If this object does not know the identity of the user who lasted updated it, the returned ID will be UserAccountable.NULL_USER_ID.

Specified by:

getLastUpdatedBy in interface UserAccountable

Returns:

the ID of the user who most recently updated this object.

getLastUpdatedOn

public Date getLastUpdatedOn()

Description copied from interface: UserAccountable

Returns the most recent date on which this object was updated.

Specified by:

getLastUpdatedOn in interface UserAccountable

Returns:

the most recent date on which this object was updated.

fromXml

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

Creates a new catalog 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 catalog 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 SourceCatalog fromXml(Reader reader)
                             throws JAXBException,
                                    XMLStreamException

Creates a new catalog 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 catalog 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.

toXml

public String toXml()
             throws JAXBException

Returns an XML representation of this catalog.

Overrides:

toXml in class Catalog<SourceCatalogEntry,SourceGroup,SourceCatalog>

Returns:

an XML representation of this catalog.

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 catalog to writer.

Overrides:

writeAsXmlTo in class Catalog<SourceCatalogEntry,SourceGroup,SourceCatalog>

Parameters:

writer - the device to which XML is written.

Throws:

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

clone

public SourceCatalog clone()

Overrides:

clone in class Catalog<SourceCatalogEntry,SourceGroup,SourceCatalog>