ApertureDataSource

Java Interface

Probably equal to source:trunk/gnowsis/src/org/gnowsis/data/datasource/DataSource.java

Changelog:

• removed setConfigAttribute and writeConfigAttributes: the choice to store DataSource configuration and the way to do that is probably an application decision. This functionality should be moved to a utility class. Leo: yes, the configuration can be conveniently stored in either a Parameters object or a RDFMap

• setting and checking configuration: see comments in header. Leo wants to give feedback to the user if a configuration is not working properly.

 /**
  * A DataSource defines the characteristics of a source from which DataObjects
  * can be extracted. A Datasource contains all information necessary to realize
  * these objects, such as paths, usernames, passwords, etc.
  * The configuration of the datasource is passed to it using the <code>initConfiguration()</code> method.
  * Then, the configuration can be checked using the <code>checkConfiguration()</code>, 
  * where the datasource should try to contact the datasource and see if the configuration is working.
  * This is used in the configuration editor user-interface to see if the configuration works and
  * give feedback to the user if passwords, filenames, urls, etc are right.
  */
public interface DataSource {

        /**
         * get the configuration of this datasource.
         * @return the configuration
         */
        public Map getConfiguration();

        /**
         * Initialize the datasource using the passed configuration map.
         * each parameter relevant to the datasource (data path, passwords, usernames, timeouts, rules, etc) is passed
         * this method must only be called once.
         * TODO: should it check the configuration (passwords allright, etc) now or when the crawler starts?
         * @throws InitializationException when the configuration contains syntactically wrong parameters,
         * parameters that cannot be parsed. Semantical errors (not-working urls, etc) are found on 
         * first access or on checkConfiguration(). 
         */
        public void initConfiguration(Map configuration) throws InitializationException;


  /**
   * check the configuration that was passed in initConfiguration().
   * The InitializationException should contain a user-friendly
   * message that explains why this datasource does not work. If a password is wrong, the exception
   * should say so. This method is usually called once before the datasource is used or
   * after the user edited the configuration and it should check if passwords and other configs
   * are working. 
   * @throws InitializationException when the configuration cannot be used to open a datasource
   */
  public void checkConfiguration() throws InitializationException;


        /**
         * Gets the id of this data source.
         * The Aduna Interface identifies DataSources by ID and Name.
         * Gnowsis uses Uris. This ID SHOULD conform to the URI scheme norm!
         * TODO: should it be a URI or not? for future's sake: yes!
         * @return A URI identifier for the data source.
         */
        public String getID();

        /**
         * Set the ID of this data source.
         * 
         * @param id the new ID
         */
        public void setID(String id);

        /**
         * Gets the name of this data source.
         * 
         * @return A descriptive name for the data source.
         */
        public String getName();

        /**
         * Sets the name of this data source.
         * 
         * @param name A descriptive name for the data source.
         */
        public void setName(String name);
}