001    package edu.nrao.sss.model.source;
002    
003    import java.util.List;
004    
005    import edu.nrao.sss.model.RepositoryException;
006    
007    /**
008     * A provider of source catalogs.
009     * <p>
010     * <b>Version Info:</b>
011     * <table style="margin-left:2em">
012     *   <tr><td>$Revision$</td></tr>
013     *   <tr><td>$Date$</td></tr>
014     *   <tr><td>$Author$ (last person to modify)</td></tr>
015     * </table></p>
016     * 
017     * @author David M. Harland
018     * @since 2009-05-05
019     */
020    //This interface was initially back-formed from part of the HibernateSourceDao class.
021    public interface SourceCatalogProvider
022    {
023      /**
024       * Returns the catalog with the given ID, or <i>null</i> if this provider
025       * holds no such catalog.
026       * 
027       * @param id
028       *   the ID of a catalog that might be held by this provider.
029       *   
030       * @return
031       *   the catalog with the given ID, or <i>null</i> if this provider holds
032       *   no such catalog.
033       *   
034       * @throws RepositoryException
035       *   if anything goes wrong while trying to fetch catalogs from this provider.
036       */
037      public SourceCatalog findCatalogById(long id) throws RepositoryException;
038    
039      /**
040       * Returns a list of all catalogs held by this provider with the given name.
041       * 
042       * @param name
043       *   the name of one or more catalogs that might be held by this provider.
044       *   
045       * @return
046       *   a list of all catalogs with the given name.
047       *   If the provider has no such catalogs the returned list will be empty.
048       * 
049       * @throws RepositoryException
050       *   if anything goes wrong while trying to fetch catalogs from this provider.
051       */
052      public List<SourceCatalog> findCatalogByName(String name) throws RepositoryException;
053    
054      /**
055       * Returns a list of all catalogs held by this provider and owned by the user
056       * with the given ID.
057       * 
058       * @param ownerId
059       *   the ID of a user who might own catalogs held by this provider.
060       *   
061       * @return
062       *   a list of all catalogs owned by the given user.
063       *   If the provider has no such catalogs the returned list will be empty.
064       * 
065       * @throws RepositoryException
066       *   if anything goes wrong while trying to fetch catalogs from this provider.
067       */
068      public List<SourceCatalog> findCatalogsOwnedBy(long ownerId) throws RepositoryException;
069     
070      /**
071       * Returns a list of all public catalogs held by this provider.
072       * A <i>public</i> catalog is one that is shared by an owner with all users,
073       * at least for read-only operations.
074       * 
075       * @return
076       *   a list of all public catalogs held by this provider.
077       *   If the provider has no public catalogs the returned list will be empty.
078       * 
079       * @throws RepositoryException
080       *   if anything goes wrong while trying to fetch catalogs from this provider.
081       */
082      public List<SourceCatalog> findPublicCatalogs() throws RepositoryException;
083    
084      /**
085       * Returns a list of all catalogs held by this provider.
086       * 
087       * @return
088       *   a list of all catalogs held by this provider.
089       *   If the provider has no catalogs the returned list will be empty.
090       * 
091       * @throws RepositoryException
092       *   if anything goes wrong while trying to fetch catalogs from this provider.
093       */
094      public List<SourceCatalog> getCatalogs() throws RepositoryException;
095    }