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