// Registries.java
//
// Created: October 2006
//
// This file is a component of the BioMoby project.
// Copyright Martin Senger (martin.senger@gmail.com).
//

package org.biomoby.registry.meta;

import org.biomoby.shared.MobyException;

/**
 * An interface defining properties (such as endpoints) of all known
 * BioMoby registries. <p>
 *
 * Its implementation can be used in order to easily select a registry
 * from a list of known registries.
 *
 * @author <A HREF="mailto:martin.senger@gmail.com">Martin Senger</A>
 * @version $Id: Registries.java,v 1.1 2006/10/02 17:57:49 senger Exp $
 */

public interface Registries {

    /**
     * A synonym (abbreviation) used for a default BioMoby registry. <p>
     *
     * @see #list list
     */
    static String DEFAULT_REGISTRY_SYNONYM = "default";

    /*********************************************************************
     * Return a list of synonyms (abbreviations) of all known BioMoby
     * registries. It should always return at least a {@link
     * #DEFAULT_REGISTRY_SYNONYM default} synonym that represents a
     * default BioMoby registry. <p>
     *
     * The returned synonyms can be used in the {@link #get get}
     * method. <p>
     *
     * @return always a non-empty array
     * 
     ********************************************************************/
    String[] list();


    /*********************************************************************
     * Return an object with properties of a given BioMoby registry. <p>
     *
     * @param synonym is the name (abbreviation) of a BioMoby registry
     * whose properties shall be returned; it can be null - in which
     * case properties of a default BioMoby registry are returned
     *
     * @return properties of the given registry
     *
     * @throws MobyException if the given 'synonym' does not represent
     * any known registry
     * 
     ********************************************************************/
    Registry get (String synonym)
	throws MobyException;

    /*********************************************************************
     * Return properties of all known BioMoby registries. At least one
     * registry (the default one) should be always included.<p>
     *
     * @return always a non-empty array
     * 
     ********************************************************************/
    Registry[] getAll();

}