urlhandler.java

一个完整的XACML工程,学习XACML技术的好例子!

/*
* Copyright (c) 2000-2005, University of Salford
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without 
* modification, are permitted provided that the following conditions are met:
*
* Redistributions of source code must retain the above copyright notice, this 
* list of conditions and the following disclaimer.
* 
* Redistributions in binary form must reproduce the above copyright notice, 
* this list of conditions and the following disclaimer in the documentation 
* and/or other materials provided with the distribution. 
*
* Neither the name of the University of Salford nor the names of its 
* contributors may be used to endorse or promote products derived from this 
* software without specific prior written permission. 
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
* POSSIBILITY OF SUCH DAMAGE.
*/

package issrg.pba.rbac;

import java.util.Map;
import java.util.Hashtable;
import java.security.Principal;
import issrg.utils.repository.Entry;
import issrg.pba.rbac.policies.Subtree;
import issrg.pba.rbac.policies.URLSubtree;
import issrg.utils.repository.FileRepository;
import issrg.utils.repository.RepositoryException;

/**
 * This class is a constructor of various URL-related instances: 
 * Subtrees (for domain matching), Principals and Entries (for domain matching).
 * It also maintains a register of URL Handlers for other protocols, so that
 * a relevant URL Handler can be found for a specific URL.
 *
 * <p>The instances of this class handle all URLs as if they were HTTP URLs.
 * Subclass it and override the methods to handle URLs of other types.
 *
 * @author A.Otenko
 * @version 1.0
 */
public class URLHandler {

  public static final String HTTP_PROTOCOL = "http";
  public static final String HTTPS_PROTOCOL = "https";
  public static final String FILE_PROTOCOL = "file";

  public static final int HTTP_PORT = 80;
  public static final int HTTPS_PORT = 443;

  /**
   * This variable is here to allow emulation of file: URLs as HTTP URLs.
   */
  protected static final int FILE_PORT = 0;

  private static Map protocols = new Hashtable();

  static{
    addProtocol(new URLHandler(HTTP_PROTOCOL, HTTP_PORT));
    addProtocol(new URLHandler(HTTPS_PROTOCOL, HTTPS_PORT));
    addProtocol(new URLHandler(FILE_PROTOCOL, FILE_PORT));
    addProtocol(new LDAPURLHandler());
  }

  /**
   * This method registers a new protocol URL handler, so if a URL
   * for this protocol has to be parsed, the getPrincipal and getSubtree nodes
   * will know who can handle such URLs.
   *
   * @param u the URLHandler that can handle URLs for a specific protocol
   */
  public static void addProtocol(URLHandler u){
    protocols.put(u.getProtocol().toLowerCase(), u);
  }

  /**
   * This method removes a protocol handler for a particular protocol name.
   *
   * @param protocol the protocol name for which handler has to be removed
   */
  public static void removeProtocol(String protocol){
    protocols.remove(protocol.toLowerCase());
  }

  /**
   * This method returns a handler for URLs for a given protocol.
   *
   * @param protocol the protocol to get the handler for
   *
   * @return the URLHandler object handling URLs for a given protocol; null, if no handler
   *   has been assigned
   */
  public static URLHandler getURLHandler(String protocol){
    if (protocol==null) return null;
    return (URLHandler)protocols.get(protocol.toLowerCase());
  }

  /**
   * This method returns the protocol name, given a URL.
   *
   * @param url the URL to get the protocol name from
   *
   * @return the protocol name as it is in the URL
   *
   * @throws BadURLException if this is not a URL with a protocol string in it
   */
  public static String getProtocolName(String url) throws BadURLException {
    if (url==null) return null;

    int i = url.indexOf(":"); // find the position of the first colon character
    if (i<0) throw new BadURLException("URL "+url+" does not have a protocol part");

    return url.substring(0, i);
  }

  /**
   * This method returns a Principal, created by corresponding URLHandler.
   *
   * <p>This is equivalent to getURLHandler(getProtocolName(url)).getPrincipal(url);
   *
   * @param url the URL as the Principal
   *
   * @return the Principal object, created by corresponding URLHandler; null, if no
   *   matching URLHandler has been found
   *
   * @throws BadURLException if the URL does not have a protocol part, or the
   *   URLHandler doesn't like it
   */
  public static Principal getPrincipalByURL(String url) throws BadURLException {
    URLHandler uh = getURLHandler(getProtocolName(url));

    return uh==null? null: uh.getPrincipal(url);
  }


  /**
   * This method returns a Entry object, created by corresponding URLHandler.
   *
   * <p>This is equivalent to getURLHandler(getProtocolName(url)).getEntry(url);
   *
   * @param url the URL of the Entry
   *
   * @return the Entry object, created by corresponding URLHandler; null, if no
   *   matching URLHandler has been found
   *
   * @throws BadURLException if the URL does not have a protocol part, or the
   *   URLHandler doesn't like it
   */
  public static Entry getEntryByURL(String url) throws BadURLException {

    URLHandler uh = getURLHandler(getProtocolName(url));
    return uh==null? null: uh.getEntry(url);
  }

  /**
   * This method returns a Subtree object, created by corresponding URLHandler.
   *
   * <p>This is equivalent to getURLHandler(getProtocolName(url)).getSubtree(url, min, max);
   *
   * @param url the URL of the base Entry
   * @param min the minimum number of levels below the base Entry where the
   *   matching entries can be located; pass 0, if no retriction is placed
   * @param max the maximum number of levels below the base Entry where the
   *   matching entries can be located; pass -1 if no restriction is placed
   * @param exclude the array of the subtrees specifying what entries to exclude
   *   from this subtree
   *
   * @return the Subtree object, created by corresponding URLHandler; null, if no
   *   matching URLHandler has been found
   *
   * @throws BadURLException if the URL does not have a protocol part, or the
   *   URLHandler doesn't like it
   */
  public static Subtree getSubtreeByURL(String url, int min, int max, Subtree [] exclude) throws BadURLException {
    URLHandler uh = getURLHandler(getProtocolName(url));
    return uh==null? null: uh.getSubtree(url, min, max, exclude);
  }

  /**
   * This method will find a URLHandler for the protocol and create the
   * AttributeRepository that will provide access to that repository.
   *
   * <p>Same as URLHandler.getURLHandler(URLHandler.getProtocolName(url)).getRepository(url);
   *
   * @param url - the URL of the repository
   *
   * @return AttributeRepository pointed to by the URL, or null, if no repository
   *    could be created (e.g. no URLHandler could be found)
   *
   * @throws BadURLException if the URL is malformed
   */
  public static issrg.utils.repository.AttributeRepository getRepositoryByURL(String url) throws BadURLException {
	//System.err.println("getting a repository for "+url);//***************
    URLHandler uh = getURLHandler(getProtocolName(url));
    return uh==null? null: uh.getRepository(url);
  }

  protected URLHandler(){}

  protected String protocol;
  protected int defaultPort;

  /**
   * This constructor builds an instance of URLHandler that will be able to 
   * handle
   * URLs of given protocol, and listening on given default port.
   *
   * @param protocol the string name of the protocol (without trailing ":"); 
   *   case of characters is ignored
   * @param defaultPort the number of the default port the protocol listens on
   */
  public URLHandler(String protocol, int defaultPort){
    this.protocol=protocol.toLowerCase();
    this.defaultPort=defaultPort;
  }

  /**
   * This method returns the string name of the protocol (without the trailing 
   * colon).
   * The protocol is in lowercase letters.
   *
   * @return string name of the protocol in lowercase characters
   */
  public String getProtocol(){
    return protocol;
  }

  /**
   * This method returns the number of the defaul port that the protocol listens 
   * on
   *
   * @return integer number of the port on which the protocol listens by default
   */
  public int getDefaultPort(){
    return defaultPort;
  }

  /**
   * This method returns a Principal for a given HTTP URL string.
   * It checks if the passed URL string matches the protocol this Handler is
   * registered for.
   *
   * @param url the string representation of the HTTP URL (including the 
   *   protocol name part)
   *   (the actual protocol name is checked with the string returned by 
   *   getProtocol,
   *   but the format of the rest of the URL is as specified in HTTP RFC)
   *
   * @return Principal of the corresponding URL
   *
   * @throws BadURLException if the URL is malformed
   */
  public Principal getPrincipal(String url) throws BadURLException {
    URLPrincipal upi=new URLPrincipal(url, defaultPort);

    if (!upi.getProtocol().equals(protocol)){
      throw new BadURLException("Wrong URL parser: "+upi.getProtocol()+": found, "+protocol+": expected");
    }

    return upi;
  }

  /**
   * This method returns an Entry identified by a given HTTP URL.
   *
   * <p>This URLHandler does (Entry)getPrincipal(url) - so if your Principal
   * implements the Entry interface, you can leave the getEntry method. 
   *
   * @param url the string representation of the HTTP URL (see comments for 
   *   getPrincipal method)
   *
   * @return Entry identified by the URL
   *
   * @throws BadURLException if the URL is malformed
   */
  public Entry getEntry(String url) throws BadURLException {
    return (Entry)getPrincipal(url); // invoke the same method, so it will do the same checks
  }

  /**
   * This method returns a Subtree specified using a Base Entry URL and Min 
   * and Max level 
   * specifications.
   *
   * @param url the URL of the Base Entry; port may be specified as a range of 
   *   ports by using nn-mm notation (two numbers separated by hyphen);
   *   if no port is specified, any port matches the subtree specification
   * @param min the Min value for the subtree
   * @param max the Max value for the subtree
   *
   * @see issrg.pba.rbac.policies.Subtree
   *
   * @throws BadURLException if the URL is malformed
   */
  public Subtree getSubtree(String url, int min, int max, Subtree [] exclude) throws BadURLException {
    return new URLSubtree(url, defaultPort, min, max, exclude);
  }

  /**
   * This method returns an instance of a repository that would be able to
   * retrieve attributes given the URL. Some Repositories may use only the
   * host part of the URL to connect to the server, ignoring the path part.
   *
   * <p>In this version of the URLHandler, no HTTP/HTTPS repositories are
   * implemented, so null is returned for such URLs.
   *
   * @param url - the URL of the repository
   *
   * @return the AttributeRepository
   */
  public issrg.utils.repository.AttributeRepository getRepository(String url) throws BadURLException {
    if (!protocol.equals(FILE_PROTOCOL)) return null;

    try{
      return new FileRepository(url);
    }catch (RepositoryException re){
      throw new BadURLException("File Repository could not be connected: "+url, re);
    }
  }
}