/*
    * Copyright (C) 2006  Tom Gibara
    *
    * This library is free software; you can redistribute it and/or
    * modify it under the terms of the GNU Lesser General Public
    * License as published by the Free Software Foundation; either
    * version 2.1 of the License, or (at your option) any later version.
    *
    * This library is distributed in the hope that it will be useful,
   * but WITHOUT ANY WARRANTY; without even the implied warranty of
   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   * Lesser General Public License for more details.
   *
   * You should have received a copy of the GNU Lesser General Public
   * License along with this library; if not, write to the Free Software
   * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
   */
  package com.tomgibara.pronto.config.source;
  
  import java.io.BufferedInputStream;
  import java.io.IOException;
  import java.io.InputStream;
  import java.net.URL;
  import java.net.URLConnection;
  import java.util.Map;
  
  import com.tomgibara.pronto.config.ConfigSource;
  import com.tomgibara.pronto.util.Arguments;
  import com.tomgibara.pronto.util.Streams;
  
  /**
   * Accesses a (possibly) remote resource that is been specified via a URL and
   * parses it into a collection of property values.
   * 
   * Instances of this class are not safe for concurrent use. Wrap instances in a
   * SynchronousConfigSource if thread safety is required.
   * 
   * @author Tom Gibara
   */
  
  public class URLConfigSource implements ConfigSource {
  
      /**
       * The URL from which the properties resource is loaded.
       */
  
      private final URL url;
  
      /**
       * The reader which converts the connection streams into properties.
       */
  
      private final PropertiesReader reader;
  
      /**
       * The time at which the properties resource was last modified.
       * 
       * Value of -1 indicates never retrieved. Value of 0 indicates retrieved but
       * unknown.
       */
  
      private long lastModified = -1L;
  
      /**
       * The time at which the properties resource is to expire.
       * 
       * Value of -1 indicates never retrieved. Value of 0 indicates retrieved but
       * unknown.
       */
  
      private long expires = -1L;
  
      /**
       * The properties that were last read from the resource. A null value
       * indicates that the properties have never before been retrieved.
       */
  
      private Map<String, String> properties = null;
  
      // constructors
  
      /**
       * Constructs a source which reads its properties from a URL using a
       * DefaultPropertiesReader.
       * 
       * @param url
       *            the location of the resource which contains the properties to
       *            be loaded, not null
       */
  
      public URLConfigSource(final URL url) {
          this(url, null);
      }
  
      /**
       * Constructs a source which reads its properties from a URL using the
       * supplied properties reader. If a null reader is supplied to this
       * constructor, a DefaultPropertiesReader is used.
       * 
      * @param url
      *            the location of the resource which contains the properties to
      *            be loaded, not null
      * @param reader
      *            a properties reader which can convert the resource into a set
      *            of properties, may be null
      */
 
     public URLConfigSource(final URL url, final PropertiesReader reader) {
         Arguments.notNull(url, "url");
         this.url = url;
         this.reader = reader == null ? DefaultPropertiesReader.PLAIN : reader;
     }
 
     // accessors
 
     /**
      * The URL from which the properties are loaded.
      * 
      * @return the url for this source, never null
      */
 
     public URL getURL() {
         return url;
     }
 
     /**
      * The reader which converts this source's resources into properties.
      * 
      * @return the properties reader for this source
      */
 
     public PropertiesReader getReader() {
         return reader;
     }
 
     // config source methods
 
     /**
      * @return the last time at which the resource identified by this source's
      *         URL was declared to have changed
      * @throws RuntimeException
      *             if an IOException was raised when accessing the resource
      */
 
     public long lastModified() throws RuntimeException {
         update();
         return lastModified;
     }
 
     /**
      * @return the properties read from the resource identified by this source's
      *         URL
      * @throws RuntimeException
      *             if an IOException was raised when accessing the resource
      */
 
     public Map<String, String> getProperties() throws RuntimeException {
         update();
         return properties;
     }
 
     // protected methods
 
     /**
      * This method is responsible for obtaining a connection to the URL for this
      * source, configuring it, calling the connect() method on it and then
      * returning the connection. This method may be overridden to customize the
      * connection to the URL.
      * 
      * The default implementation simply opens the connection, calls connect and
      * then returns.
      * 
      * @return an opened, connected <code>URLConnection</code>
      * @throws IOException
      *             if the connection raises an IOException
      */
 
     protected URLConnection connectToURL() throws IOException {
         URLConnection connection = getURL().openConnection();
         connection.connect();
         return connection;
     }
 
     // private utility methods
 
     /**
      * Updates the lastModified, expires and properties fields of this object. A
      * good attempt is made at
      * 
      * 
      * @throws RuntimeException
      *             in the event that the an IOException occurs
      */
 
     private void update() throws RuntimeException {
         long now = 0L;
         if (properties != null) { // if we already have properties, maybe we
             // have nothing more to do?
             if (expires > 0L) {
                 now = System.currentTimeMillis();
                 if (now < expires) return; // the resources haven't expired yet
             }
         }
         // fall through to obtain properties - first make sure we know 'now'
         if (now == 0L) now = System.currentTimeMillis();
 
         try {
             // first: establish a connection
             URLConnection connection = connectToURL();
 
             // TODO check the validity of the response - eg use LMS header
 
             // second: identify if the resource has changed
             boolean changed;
             long newLastModified = connection.getLastModified();
             // this tests for one of:
             // lastModified == -1 (never before read) - implied by:
             // lastModified < newLastModified (has changed)
             // newLastModified == 0 (we now don't know the last modified)
             if (lastModified < newLastModified || newLastModified == 0) {
                 lastModified = newLastModified;
                 expires = connection.getExpiration();
                 changed = true;
             } else { // there's been no change
                 // the resource's lease may have changed independently of the
                 // resource
                 expires = connection.getExpiration();
                 changed = false;
             }
 
             // third: read in the properties if necessary
             // we get the input stream any way because we need to close it
             InputStream in = null;
             try {
                 in = connection.getInputStream();
                 if (properties == null || changed) {
                     in = new BufferedInputStream(in);
                     properties = reader.read(in);
                 }
             } finally {
                 Streams.safeClose(in);
             }
         } catch (IOException e) {
             throw new RuntimeException(e);
         }
     }
 }