attributerepository.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.
*/
/*
* Copyright (c) 2006, University of Kent
* 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. 
*
* 1. Neither the name of the University of Kent nor the names of its 
* contributors may be used to endorse or promote products derived from this 
* software without specific prior written permission. 
*
* 2. 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. 
*
* 3. 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.
*
* 4. YOU AGREE THAT THE EXCLUSIONS IN PARAGRAPHS 2 AND 3 ABOVE ARE REASONABLE
* IN THE CIRCUMSTANCES.  IN PARTICULAR, YOU ACKNOWLEDGE (1) THAT THIS
* SOFTWARE HAS BEEN MADE AVAILABLE TO YOU FREE OF CHARGE, (2) THAT THIS
* SOFTWARE IS NOT "PRODUCT" QUALITY, BUT HAS BEEN PRODUCED BY A RESEARCH
* GROUP WHO DESIRE TO MAKE THIS SOFTWARE FREELY AVAILABLE TO PEOPLE WHO WISH
* TO USE IT, AND (3) THAT BECAUSE THIS SOFTWARE IS NOT OF "PRODUCT" QUALITY
* IT IS INEVITABLE THAT THERE WILL BE BUGS AND ERRORS, AND POSSIBLY MORE
* SERIOUS FAULTS, IN THIS SOFTWARE.
*
* 5. This license is governed, except to the extent that local laws
* necessarily apply, by the laws of England and Wales.
*/

package issrg.utils.repository;

/**
 * This interface defines the basic methods that can be performed on a read-only
 * repository. It provides methods for retrieving attributes from a given entry
 * (attributes and entries are terms like for the Directory). Besides this the
 * caller can enquire on the status of the repository between calls to react 
 * more
 * intelligently should an outage occur.
 *
 * <p>Note that some terms (like DN) are Directory-like, but in fact they are
 * treated in a quite general fashion, and the interface does not require them
 * to be DNs, if the implementation uses a different naming convention.
 *
 * <p>For better multi-threaded support it is advised that the methods were
 * NOT synchronized, so that multiple threads could request attributes 
 * simultaneously. Note also that if you do need them to be synchronized, make
 * sure that there will be no recursive invocation of it from multiple threads.
 * For example, MultiRepository spawns multiple threads that often invoke the
 * same MultiRepository; if somehow your repository invokes getAttributes on 
 * the same MultiRepository that called it, the synchronized method in your 
 * repository may block execution. So the remedy is: don't wrap repositories 
 * that may call you, or don't use synchronized methods.
 *
 * @author A Otenko
 * @version 1.0
 *
 * @see MultiRepository
 */

public interface AttributeRepository {
  /**
   * This is a status code for when everything is alright with the repository. 
   * Particularly, the
   * last function call succeeded.
   */
  public final static int SUCCESS_STATUS = 0;

  /**
   * This is a status code for when an unrecoverable error occurred.
   */
  public final static int FAILURE_STATUS = 1;

  /**
   * This is a status code for when the repository succeeded to execute the 
   * call only partially. For example, only part of attributes were returned.
   */
  public final static int PARTIAL_SUCCESS_STATUS = 2;

  /**
   * This is when the repository failed to process a request because any of the
   * previous calls returned an unfavourable result. Generally, this means that
   * you should have checked the status before calling and calculate your
   * decision to call this method more carefully. Repository implementations
   * may not use this error code at all.
   */
  public final static int INHERENT_FAILURE_STATUS = 3;

  /**
   * This method returns the given attribute or null, if the attribute is not 
   * present
   * in the given entry of the repository. Does effectively the same as
   * <p><code>getAttributes(DN, new String[]{AttributeName});</code>
   * <p>though, returns one attribute only.
   *
   * @param DN is the Principal, for which to retrieve the attribute
   * @param AttributeName is a repository attribute name of the attribute to 
   *   return
   *
   * @return an Attribute with multiple values, retrieved from the Repository;
   *        can be null, if no such attribute exists in the given entry
   *
   * @throws RepositoryException, if no such entry exists, or other error occurs
   *   during the call
   */
  public javax.naming.directory.Attribute getAttribute(java.security.Principal DN, String AttributeName) throws RepositoryException;

  /**
   * This method does the same as <code>getAttribute</code> for each of the 
   * specified attributes
   * in the attribute list. It looks in the named entry for the set
   * of attributes. It returns any of the attributes found. Some of the
   * attributes may be missing in the entry.
   *
   * @param DN is the Principal, for which to retrieve the attributes
   * @param AttributeNames is an array of repository attribute names of 
   *    the attributes to
   *    return; returns all attributes available, if the array is null
   *
   * @return an Attributes object with multiple values for each attribute,
   *    retrieved from the Repository; can be either an empty set of attributes
   *    or null, if no such attributes exist
   *
   * @throws RepositoryException, if no such entry exists, or other error occurs
   *   during the call
   */
  public javax.naming.directory.Attributes getAttributes(java.security.Principal DN, String [] AttributeNames) throws RepositoryException;

  /**
   * This method returns the collection of all attributes and all of their
   * values. Does exactly the same as
   * <p><code>getAttributes(DN, null);</code>
   *
   * @param DN is the Principal, for which to retrieve the attributes
   *
   * @return an Attributes object, containing all values of all attributes of
   *      the given Principal; can be an empty set of attributes or null, if no
   *      attributes exist
   *
   * @throws RepositoryException, if no such entry exists, or other error occurs
   *   during the call
   */
  public javax.naming.directory.Attributes getAllAttributes(java.security.Principal DN) throws RepositoryException;


  /**
   * This method returns the status of the Repository.
   *
   * @return one of the *_STATUS values
   *
   * @see #SUCCESS_STATUS
   * @see #FAILURE_STATUS
   * @see #PARTIAL_SUCCESS_STATUS
   * @see #INHERENT_FAILURE_STATUS
   */
  public int getStatus();

  /**
   * This method returns the last Exception thrown or an exception the 
   * Repository wanted
   * to throw very much, but did not, only because the error was not
   * fatal.
   *
   * <p><b>TODO:</b> I am very keen to remove getStatus() method, and return
   * DiagnosisException only; which will contain the status code in it and a
   * reference to an embedded exception. Thus it will be possible to throw such
   * an exception in cases of need, and still it will be possible to keep it
   * for further information. I envisage that the PbaException is one of this
   * sort: a DiagnosisException.
   *
   * @return the last Throwable the Repository was eager to throw or has thrown
   *
   * @see #getStatus()
   */
  public Throwable getDiagnosis();
}