/*
 * 
 * Copyright 2004 Sun Microsystems, Inc. All Rights Reserved.
 * 
 * The contents of this file are subject to the Sun Community Source
 * License v3.0/Jini Technology Specific Attachment v 1.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://wwws.sun.com/software/jini/licensing/SCSL3_JiniTSA1.html.
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 * 
 * The Reference Code is Jini Technology Core Platform code, v2.0. The
 * Developer of the Reference Code is Sun Microsystems, Inc.
 * 
 * Contributor(s): Sun Microsystems, Inc.
 * 
 * The contents of this file comply with the Jini Technology Core
 * Platform Compatibility Kit, v2.0A.
 * 
 * Tester(s): Sun Microsystems, Inc.
 * 
 * Test Platform(s):
 * Java 2 SDK, Standard Edition, Version 1.4.2_03 for Solaris(TM)SPARC/x86
 * Java 2 SDK, Standard Edition, Version 1.4.2_03 for Linux (Intel x86)
 * Java 2 SDK, Standard Edition, Version 1.4.2_03 for Windows (Intel Platform)
 * 
 */

package net.jini.security;

import java.rmi.RemoteException;
import java.util.Collection;

/**
 * Defines the interface for trust verifiers used by
 * {@link Security#verifyObjectTrust Security.verifyObjectTrust}, allowing
 * the objects that are trusted to be extended.
 *
 * @author Sun Microsystems, Inc.
 * 
 * @since 2.0
 */
public interface TrustVerifier {
    /**
     * Returns <code>true</code> if the specified object is known to be
     * trusted to correctly implement its contract; returns <code>false</code>
     * otherwise.
     *
     * @param obj the object in which to verify trust
     * @param ctx the trust verifier context, to aid in verification of
     * the specified object and its components
     * @return <code>true</code> if the specified object is known to be
     * trusted to correctly implement its contract; <code>false</code>
     * otherwise
     * @throws RemoteException if a communication-related exception occurs
     * @throws SecurityException if a security exception occurs
     * @throws NullPointerException if any argument is <code>null</code>
     */
    boolean isTrustedObject(Object obj, Context ctx)
	throws RemoteException;

    /**
     * Defines the context for trust verification used by
     * {@link TrustVerifier} instances and {@link Security#verifyObjectTrust
     * Security.verifyObjectTrust}. A context contains an ordered list of
     * {@link TrustVerifier} instances, a class loader, and a collection of
     * other context objects typically provided by the caller of
     * <code>Security.verifyObjectTrust</code>.
     *
     * @since 2.0
     */
    public interface Context {
	/**
	 * Returns <code>true</code> if the specified object is trusted to
	 * correctly implement its contract; returns <code>false</code>
	 * otherwise.
	 * <p>
	 * If the specified object is <code>null</code>, this method returns
	 * <code>true</code>. Otherwise, the
	 * {@link TrustVerifier#isTrustedObject isTrustedObject} method of
	 * each verifier contained in this context is called (in order) with
	 * the specified object and this context. If any verifier call returns
	 * <code>true</code>, the object is trusted and this method returns
	 * <code>true</code>. If all of the verifier calls return
	 * <code>false</code>, this method returns <code>false</code>.
	 * If one or more verifier calls throw a <code>RemoteException</code>
	 * or <code>SecurityException</code>, the last such exception is
	 * thrown to the caller (unless some verifier call returns
	 * <code>true</code>).
	 *
	 * @param obj the object in which to verify trust
	 * @return <code>true</code> if the specified object is trusted to
	 * correctly implements its contract; <code>false</code> otherwise
	 * @throws RemoteException if a communication-related exception occurs
	 * @throws SecurityException if a security exception occurs
	 */
	boolean isTrustedObject(Object obj) throws RemoteException;

	/**
	 * Returns the class loader that can be used as a basis for trust
	 * verification. In particular, classes and resources reachable from
	 * this class loader can be assumed to be trustworthy. A
	 * <code>null</code> value is interpreted to mean the current context
	 * class loader.
	 *
	 * @return the class loader that can be used as a basis for trust
	 * verification
	 */
	ClassLoader getClassLoader();

	/**
	 * Returns a collection of context objects for use by trust verifiers.
	 * The meaning of an element in this collection is determined by its
	 * type. As a specific example, a
	 * {@link net.jini.core.constraint.MethodConstraints}
	 * instance could be used to specify client constraints for any remote
	 * calls that trust verifiers might need to perform.
	 *
	 * @return a collection of context objects for use by trust verifiers
	 */
	Collection getCallerContext();
    }
}
