/*
 * Address.java February 2001
 *
 * Copyright (C) 2001, Niall Gallagher <niallg@users.sf.net>
 *
 * Licensed 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.
 */
 
package org.simpleframework.http;

import org.simpleframework.util.KeyMap;

/** 
 * The <code>Address</code> interface is used to represent a generic
 * uniform resource identifier. This interface allows each section 
 * of the uniform resource identifier to be represented. A generic
 * uniform resource identifier syntax is represented in RFC 2616 
 * section 3.2.2 for the HTTP protocol, this allows similar URI's
 * for example ftp, http, https, tftp. The syntax is
 * <code><pre>
 *
 *    URI = [scheme "://"] host [ ":" port ] [ path [ "?" query ]]
 *
 * </pre></code>
 * This interface represents the host, port, path and query part
 * of the uniform resource identifier. The parameters are also 
 * represented by the URI. The parameters in a URI consist of name 
 * and value pairs in the path segment of the URI.
 * <p>
 * This will normalize the path part of the uniform resource
 * identifier. A normalized path is one that contains no back
 * references like "./" and "../". The normalized path will not
 * contain the path parameters.
 *
 * @author Niall Gallagher
 */
public interface Address {

   /**
    * This allows the scheme of the URL given to be returned.
    * If the URI does not contain a scheme then this will
    * return null. The scheme of the URI is the part that
    * specifies the type of protocol that the URI is used
    * for, an example <code>http://domain/path</code> is
    * a URI that is intended for the http protocol. The
    * scheme is the string <code>http</code>.
    * 
    * @return the scheme tag for the address if available
    */
   public String getScheme();

   /** 
    * This is used to retrieve the domain of this URI. The 
    * domain part in the URI is an optional part, an example
    * <code>http://domain/path?querypart</code>. This will 
    * return the value of the domain part. If there is no 
    * domain part then this will return null otherwise the 
    * domain value found in the uniform resource identifier.
    *
    * @return the domain part of the address if available
    */
   public String getDomain();

   /** 
    * This is used to retrieve the port of the uniform resource 
    * identifier. The port part in this is an optional part, an 
    * example <code>http://host:port/path?querypart</code>. This 
    * will return the value of the port. If there is no port then 
    * this will return <code>-1</code> because this represents 
    * an impossible uniform resource identifier port. The port 
    * is an optional part.
    *   
    * @return this returns the port part if it is available
    */   
   public int getPort();
   
   /** 
    * This is used to retrieve the path of this URI. The path part 
    * is the most fundamental part of the URI. This will return 
    * the value of the path. If there is no path part then this 
    * will return a Path implementation that represents the root
    * path represented by <code>/</code>. 
    * 
    * @return the path part of the uniform resource identifier
    */
   public Path getPath();

   /** 
    * This is used to retrieve the query of this URI. The query part 
    * in the URI is an optional part. This will return the value 
    * of the query part. If there is no query part then this will 
    * return an empty <code>Query</code> object. The query is 
    * an optional member of a URI and comes after the path part, it
    * is preceded by a question mark, <code>?</code> character. 
    * For example the following URI contains <code>query</code> for
    * its query part, <code>http://host:port/path?query</code>.
    * <p>
    * This returns a <code>org.simpleframework.http.Query</code> 
    * object that can be used to interact directly with the query 
    * values. The <code>Query</code> object is a read-only interface
    * to the query parameters, and so will not affect the URI.
    *
    * @return a <code>Query</code> object for the query part
    */ 
   public Query getQuery();

   /**
    * This extracts the parameter values from the uniform resource
    * identifier represented by this object. The parameters that a  
    * uniform resource identifier contains are embedded in the path 
    * part of the URI. If the path contains no parameters then this
    * will return an empty <code>Map</code> instance. 
    * <p>
    * This will produce unique name and value parameters. Thus if the 
    * URI contains several path segments with similar parameter names
    * this will return the deepest parameter. For example if the URI
    * represented was <code>http://domain/path1;x=y/path2;x=z</code>
    * the value for the parameter named <code>x</code> would be
    * <code>z</code>.
    *
    * @return this will return the parameter names found in the URI
    */
   public KeyMap<String> getParameters();

   /** 
    * This is used to convert this URI object into a <code>String</code> 
    * object. This will only convert the parts of the URI that exist, so 
    * the URI may not contain the domain or the query part and it will 
    * not contain the path parameters. If the URI contains all these 
    * parts then it will return something like 
    * <pre>
    * scheme://host:port/path/path?querypart
    * </pre>
    * <p>
    * It can return <code>/path/path?querypart</code> style relative 
    * URI's. If any of the parts are set to null then that part will be 
    * missing, for example if only the path is available then this will
    * omit the domain, port and scheme. Showing a relative address.
    * <pre>
    * scheme://host:port/?querypart
    * </pre>
    *
    * @return the URI address with the optional parts if available
    */
   public String toString();
}