/* $Id$
 *
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements. See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership. The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License. You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied. See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */

module org.apache.etch.services.config

/**
 * Configuration service provides access to configuration data. The data is
 * modeled as a general tree structure with a root node which might be a scalar
 * (boolean, int, double, string, Datetime), a List, or a Map. A List is
 * indexed by int starting at 0, while a Map is indexed by non-empty string,
 * generally following identifier syntax (case-sensitive, initial alpha then
 * alphanumeric) but not required to. Each node in this tree is assigned an id.
 * The id of the root node is null.
 *
 * At a given node in the tree, you may navigate up to the parent, down to the
 * children, get the name, get the path (absolute, from the root), get the value
 * if a scalar, enumerate the children if a List or Map, test if it is the root,
 * a List, or a Map.
 *
 * This interface is only used to query configuration data, it does not include
 * a facility to list available configurations, nor to manage configurations. It
 * also does not include methods to alter existing configuration data, but it
 * does allow you to subscribe to receive notification of changes.
 *
 * Configuration data is organized into separate spaces. The space is called out
 * by name. You must have authorization to access the named space. There is no
 * particular meaning to the name outside the interpretation given by the target
 * service implementation. The configurations might come from a database, a
 * directory tree of yaml files, etc. For services, anyway, a good idea would be
 * to use the service name as it appears in the name service directory entry.
 *
 * Here is an example use of these interfaces:
 *
 * RemoteConfigurationServer server = ConfigurationHelper.newServer( ... );
 * server._startAndWaitUp( 4000 );
 * server.loadConfig( "org.apache.etch.services.ns.NameService/titan" );
 * String host = server.getStringPath( null, "host" );
 * int port = server.getIntegerPath( null, "port" );
 *
 * A path is a string delimited with '/' characters, much like a file system
 * path. A path which begins with a '/' is absolute and begins at the root.
 * Otherwise the path is relative to a specified node. The special names '.'
 * and '..' may be used to refer to the current node and the parent node.
 * When a path traverses a List, the index in the list is give as an integer in
 * the path (e.g., /users/1/age). This would refer to the age of the 2nd user
 * in a list of users. When a path is specified as null or blank, it is the same
 * as '.'.
 */
@Timeout( 30000 )
service Configuration
{
	/**
	 * ConfigurationException is used to report any problem loading a
	 * Configuration.
	 * @param msg a text description of the problem.
	 */
	exception ConfigurationException( string msg )
	
	/**
	 * Loads a configuration. Any previous configuration is discarded along
	 * with any subscriptions. Depending upon the configuration service
	 * capabilities, it may be able to monitor the configuration for changes
	 * and automatically load them.
	 * @param name the name of the configuration.
	 * @return the id of the root node.
	 * @throws ConfigurationException if there is any problem.
	 */
	@Authorize( canLoad, name )
	object loadConfig( string name )
		throws ConfigurationException
	
	/**
	 * Unloads the current configuration if any.
	 */
	void unloadConfig()
	
	/**
	 * Tests whether the configuration exists and can be loaded by this user.
	 * @param name the name of the configuration.
	 * @return true if the configuration exists and can be loaded by this user.
	 */
	boolean canLoad( string name )
	
	/**
	 * Tests whether a configuration has been loaded.
	 * @return true if a configuration has been loaded.
	 */
	boolean isLoaded()
	
	/**
	 * Returns the id of the root node.
	 * @return the id of the root node.
	 */
	object getRoot()
	
	/////////////////////
	// NODE PROPERTIES //
	/////////////////////
	
	/**
	 * Gets the parent of a node.
	 * @param id the id of a node.
	 * @return the id of the parent of the node, or null if it is the root.
	 */
	object getParent( object id )
	
	/**
	 * Gets the name of a node which is a child of a map or list.
	 * @param id the id of a node.
	 * @return the name of the node. The name is a string if the parent is a
	 * Map or a List, or "" (the empty string) if the value is the root.
	 */
	string getName( object id )
	
	/**
	 * Gets the index of a node which is a child of a list.
	 * @param id the id of a node.
	 * @return the index of the node if the parent is a list, or null otherwise.
	 */
	int getIndex( object id )
	
	/**
	 * Gets the path of a node.
	 * @param id the id of a node.
	 * @return the concatenation of the names of the ancestors of the node
	 * with "/" between the names.
	 */
	string getPath( object id )
	
	/**
	 * Tests whether a node is the root.
	 * @param id the id of a node.
	 * @return true if the node is the root.
	 */
	boolean isRoot( object id )
	
	/**
	 * Tests whether a node is a List.
	 * @param id the id of a node.
	 * @return true if the node is a List.
	 */
	boolean isList( object id )
	
	/**
	 * Tests whether a node is a Map.
	 * @param id the id of a node.
	 * @return true if the node is a Map.
	 */
	boolean isMap( object id )
	
	/**
	 * Gets the number of children of a node which is a List or Map.
	 * @param id the id of a node.
	 * @return the number of children.
	 */
	int size( object id )
	
	//////////////
	// CHILDREN //
	//////////////
	
	/**
	 * Lists the ids of the children of a node.
	 * @param id the id of a node.
	 * @param offset index into the result set of the first item to return. If
	 * null, 0 is used.
	 * @param count count of items to return. If null, all remaining items are
	 * returned.
	 * @return array of child ids, or null if the node is a scalar node.
	 */
	object[] listConfigIds( object id, int offset, int count )
	
	/**
	 * Lists the ids of the children of a node.
	 * @param id the id of a node.
	 * @param path a path relative to the node.
	 * @param offset index into the result set of the first item to return. If
	 * null, 0 is used.
	 * @param count count of items to return. If null, all remaining items are
	 * returned.
	 * @return array of child ids, or null if the node is a scalar node.
	 */
	object[] listConfigPathIds( object id, string path, int offset, int count )
	
	/**
	 * Gets the id of a child of a node by index. The node must be a List.
	 * @param id the id of a node.
	 * @param index an index of the child node. Starts at 0.
	 * @return id of the child.
	 */
	object getConfigIndex( object id, int index )

	/**
	 * Gets the id of a child of a node by path. The nodes along the path must
	 * all be a List or Map except the last. Whenever a path element is being
	 * applied to a list node, it must be an integer.
	 * @param id the id of a node.
	 * @param path a path relative to the node.
	 * @return id of the child.
	 */
	object getConfigPath( object id, string path )
	
	////////////////////////
	// NODE / PATH ACCESS //
	////////////////////////
	
	/**
	 * Tests whether a node has a value.
	 * @param id the id of a node.
	 * @param path a path relative to the node.
	 * @return true if the node has a value.
     */
	boolean hasValuePath( object id, string path )
	
	/**
	 * Gets the value value of a node.
	 * @param id the id of a node.
	 * @param path a path relative to the node.
	 * @return the value of the node, or null if none. Note that the value may
	 * not be the expected type. That depends upon the underlying
	 * implementation. If you want the value as a specific type, use
	 * getTypePath() methods below.
     */
	object getValuePath( object id, string path )

	/**
	 * Gets the boolean value of a node.
	 * @param id the id of a node.
	 * @param path a path relative to the node.
	 * @return the value of the node, or null if none.
     */
	boolean getBooleanPath( object id, string path )

	/**
	 * Gets the integer value of a node.
	 * @param id the id of a node.
	 * @param path a path relative to the node.
	 * @return the value of the node, or null if none.
     */
	int getIntegerPath( object id, string path )

	/**
	 * Gets the double value of a node.
	 * @param id the id of a node.
	 * @param path a path relative to the node.
	 * @return the value of the node, or null if none.
     */
	double getDoublePath( object id, string path )

	/**
	 * Gets the string value of a node.
	 * @param id the id of a node.
	 * @param path a path relative to the node.
	 * @return the value of the node, or null if none.
     */
	string getStringPath( object id, string path )

	/**
	 * Gets the Datetime value of a node.
	 * @param id the id of a node.
	 * @param path a path relative to the node.
	 * @return the value of the node, or null if none.
     */
	Datetime getDatePath( object id, string path )
	
	/**
	 * Gets the List value of a node.
	 * @param id the id of a node.
	 * @param path a path relative to the node.
	 * @param depth if any of the values in the list are themselves maps or
	 * lists, recursively get those values too up to the specified depth. Depth
	 * value of 0 means only get the values of the node itself.
	 * @return the List value of the node.
	 */
	List getListPath( object id, string path, int depth )
	
	/**
	 * Gets the Map value of a node.
	 * @param id the id of a node.
	 * @param path a path relative to the node.
	 * @param depth if any of the values in the map are themselves maps or
	 * lists, recursively get those values too up to the specified depth. Depth
	 * value of 0 means only get the values of the node itself.
	 * @return the Map value of the node.
	 */
	Map getMapPath( object id, string path, int depth )
	
	/////////////////
	// NODE ACCESS //
	/////////////////

	/**
	 * Tests whether a node has a value.
	 * @param id the id of a node.
	 * @return true if the node has a value.
     */
	boolean hasValue( object id )
	
	/**
	 * Gets the value value of a node.
	 * @param id the id of a node.
	 * @return the value of the node, or null if none. Note that the value may
	 * not be the expected type. That depends upon the underlying
	 * implementation. If you want the value as a specific type, use getType()
	 * methods below.
     */
	object getValue( object id )

	/**
	 * Gets the boolean value of a node.
	 * @param id the id of a node.
	 * @return the value of the node, or null if none.
     */
	boolean getBoolean( object id )

	/**
	 * Gets the integer value of a node.
	 * @param id the id of a node.
	 * @return the value of the node, or null if none.
     */
	int getInteger( object id )

	/**
	 * Gets the double value of a node.
	 * @param id the id of a node.
	 * @return the value of the node, or null if none.
     */
	double getDouble( object id )

	/**
	 * Gets the string value of a node.
	 * @param id the id of a node.
	 * @return the value of the node, or null if none.
     */
	string getString( object id )

	/**
	 * Gets the Datetime value of a node.
	 * @param id the id of a node.
	 * @return the value of the node, or null if none.
     */
	Datetime getDate( object id )
	
	/**
	 * Gets the List value of a node.
	 * @param id the id of a node.
	 * @param depth if any of the values in the list are themselves maps or
	 * lists, recursively get those values too up to the specified depth. Depth
	 * value of 0 means only get the values of the node itself.
	 * @return the List value of the node.
	 */
	List getList( object id, int depth )
	
	/**
	 * Gets the Map value of a node.
	 * @param id the id of a node.
	 * @param depth if any of the values in the map are themselves maps or
	 * lists, recursively get those values too up to the specified depth. Depth
	 * value of 0 means only get the values of the node itself.
	 * @return the Map value of the node.
	 */
	Map getMap( object id, int depth )
	
	/////////////////////////
	// CHANGE NOTIFICATION //
	/////////////////////////
	
	/**
	 * Subscribes to changes at or below a node.
	 * @param id the id of a node.
	 */
	void subscribe( object id )
	
	/**
	 * Subscribes to changes at or below a node.
	 * @param id the id of a node.
	 * @param path a path relative to the node.
	 */
	void subscribePath( object id, string path )
	
	/**
	 * Unsubscribes to changes at or below a node.
	 * @param id the id of a node.
	 */
	void unsubscribe( object id )
	
	/**
	 * Unsubscribes to changes at or below a node.
	 * @param id the id of a node.
	 * @param path a path relative to the node.
	 */
	void unsubscribePath( object id, string path )
	
	/**
	 * Unsubscribes to all changes.
	 */
	void unsubscribeAll()
	
	/**
	 * Notifies client of changes to the values of nodes. Added or deleted nodes
	 * are treated as updates to the parent. Reporting is done on a best effort
	 * basis. The nodes reported might be an ancestor of the nodes which
	 * actually changed.
	 * @param updated the ids of nodes that have been updated.
	 */
	@Direction( Client )
	@AsyncReceiver( Queued )
	void configValuesChanged( object[] updated )
}