001/*
002 * #%L
003 * Netarchivesuite - harvester
004 * %%
005 * Copyright (C) 2005 - 2014 The Royal Danish Library, the Danish State and University Library,
006 *             the National Library of France and the Austrian National Library.
007 * %%
008 * This program is free software: you can redistribute it and/or modify
009 * it under the terms of the GNU Lesser General Public License as
010 * published by the Free Software Foundation, either version 2.1 of the
011 * License, or (at your option) any later version.
012 * 
013 * This program is distributed in the hope that it will be useful,
014 * but WITHOUT ANY WARRANTY; without even the implied warranty of
015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
016 * GNU General Lesser Public License for more details.
017 * 
018 * You should have received a copy of the GNU General Lesser Public
019 * License along with this program.  If not, see
020 * <http://www.gnu.org/licenses/lgpl-2.1.html>.
021 * #L%
022 */
023package dk.netarkivet.harvester.datamodel;
024
025import java.util.Iterator;
026
027import dk.netarkivet.common.exceptions.ArgumentNotValid;
028import dk.netarkivet.common.exceptions.IOFailure;
029import dk.netarkivet.common.exceptions.UnknownID;
030
031/**
032 * Abstract class for the DAO handling the persistence of {@link HarvestChannel} instances.
033 *
034 * @author ngiraud
035 */
036public abstract class HarvestChannelDAO implements DAO, Iterable<HarvestChannel> {
037
038    /** The singleton instance */
039    private static HarvestChannelDAO instance;
040
041    /** Default empty constructor */
042    HarvestChannelDAO() {
043
044    }
045
046    /**
047     * Gets the {@link HarvestChannelDAO} singleton.
048     *
049     * @return the {@link HarvestChannelDAO} singleton
050     */
051    public static synchronized HarvestChannelDAO getInstance() {
052        if (instance == null) {
053            instance = new HarvestChannelDBDAO();
054        }
055        return instance;
056    }
057
058    @Override
059    public abstract Iterator<HarvestChannel> iterator();
060
061    /**
062     * Retrieves a {@link HarvestChannel} by its UID.
063     *
064     * @param id the UID to look for
065     * @return the corresponding instance
066     * @throws ArgumentNotValid if not ID is supplied
067     * @throws UnknownID if the ID is not present in the persistent storage.
068     */
069    public abstract HarvestChannel getById(long id) throws ArgumentNotValid, UnknownID;
070
071    /**
072     * Retrieves a {@link HarvestChannel} by its unique name.
073     *
074     * @param name the name to look for
075     * @return the corresponding instance
076     * @throws ArgumentNotValid if not name is supplied
077     * @throws UnknownID if the name is not present in the persistent storage.
078     */
079    public abstract HarvestChannel getByName(String name) throws ArgumentNotValid, UnknownID;
080
081    /**
082     * Creates a {@link HarvestChannel} object in the storage backend.
083     *
084     * @param harvestChannel the {@link HarvestChannel} object
085     */
086    public abstract void create(HarvestChannel harvestChannel) throws IOFailure;
087
088    /**
089     * Updates a {@link HarvestChannel} object in the storage backend.
090     *
091     * @param harvestChannel the {@link HarvestChannel} object
092     */
093    public abstract void update(HarvestChannel harvestChannel) throws IOFailure;
094
095    /**
096     * Returns harvest channels by type, sorted first by type (focused first, then broad) and then by name.
097     *
098     * @param includeSnapshot if true, returns the single snapshot channel in the iterator.
099     * @return an iterator on {@link HarvestChannel}.
100     */
101    public abstract Iterator<HarvestChannel> getAll(boolean includeSnapshot);
102
103    /**
104     * Returns true if a default channel exists for focused jobs.
105     *
106     * @return true if a default channel exists for focused jobs, false otherwise.
107     */
108    public abstract boolean defaultFocusedChannelExists();
109
110    /**
111     * Returns the default {@link HarvestChannel} for the given type of harvest.
112     *
113     * @param snapshot snapshot or partial harvest
114     * @return the default {@link HarvestChannel}
115     */
116    public abstract HarvestChannel getDefaultChannel(boolean snapshot);
117
118    /**
119     * Returns the {@link HarvestChannel} mapped to the given {@link HarvestDefinition} id. If no mapping was explicitly
120     * defined, returns null.
121     *
122     * @param harvestDefinitionId the {@link HarvestDefinition} id to look for
123     * @return the mapped {@link HarvestChannel} id or null
124     */
125    public abstract HarvestChannel getChannelForHarvestDefinition(long harvestDefinitionId);
126
127}