View Javadoc

1   /*
2    * Copyright (C) 2006  Tom Gibara
3    *
4    * This library is free software; you can redistribute it and/or
5    * modify it under the terms of the GNU Lesser General Public
6    * License as published by the Free Software Foundation; either
7    * version 2.1 of the License, or (at your option) any later version.
8    *
9    * This library is distributed in the hope that it will be useful,
10   * but WITHOUT ANY WARRANTY; without even the implied warranty of
11   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12   * Lesser General Public License for more details.
13   *
14   * You should have received a copy of the GNU Lesser General Public
15   * License along with this library; if not, write to the Free Software
16   * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
17   */
18  package com.tomgibara.pronto.config;
19  
20  import java.util.Map;
21  
22  /**
23   * Implementations of this interface are supplied to configs to provide the raw
24   * properties for configuration.
25   * 
26   * A config will externally synchronize calls to this interface. If a
27   * ConfigSource instance is supplied to more than one config then that instance
28   * must be safe for concurrent use.
29   * 
30   * @author Tom Gibara
31   * 
32   */
33  
34  // TODO consider providing standard empty implementation
35  // TODO consider providing a token replacing implementation
36  // TODO consider providing a domain prefixing implementation
37  public interface ConfigSource {
38  
39      /**
40       * Returns the time at which the properties were last known to have changed.
41       * This method must be implemented and MAY NOT return rogue values if the
42       * time is unknown. The correct behaviour in such circumstances is to return
43       * the current system time. If calculation of the time fails, the
44       * implementation is free to throw a runtime exception of its choosing.
45       * 
46       * @return the time at which the properties were last known to have changed,
47       *         must be positive
48       * @throws RuntimeException
49       *             if the last modified timestamp could not be generated
50       */
51  
52      long lastModified() throws RuntimeException;
53  
54      /**
55       * A map of the configuration properties supplied by this source. The map
56       * returned by this method will not be modified by the config. The
57       * implementation is free to throw an unchecked exception of its choice if
58       * the properties cannot be supplied.
59       * 
60       * @return the properties for this source, never null
61       * @throws RuntimeException
62       *             if the properties could not be supplied
63       */
64  
65      Map<String, String> getProperties() throws RuntimeException;
66  
67  }