/*
 * 
 * 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.jeri;

import net.jini.core.constraint.ConstraintAlternatives;
import net.jini.core.constraint.Integrity;
import net.jini.core.constraint.InvocationConstraints;
import net.jini.io.UnsupportedConstraintException;

/**
 * Represents the constraint support capabilities of a server-side
 * transport layer implementation.
 *
 * <p>The {@link #checkConstraints checkConstraints} method is
 * intended to be used by an {@link InvocationDispatcher} to verify
 * support for constraints.
 *
 * @author Sun Microsystems, Inc.
 * @since 2.0
 **/
public interface ServerCapabilities {

    /**
     * Verifies that this instance supports the transport layer
     * aspects of all of the specified requirements (both in general
     * and in the current security context), and returns the
     * requirements that must be at least partially implemented by
     * higher layers in order to fully satisfy all of the specified
     * requirements.  This method may also return preferences that
     * must be at least partially implemented by higher layers in
     * order to fully satisfy some of the specified preferences.
     *
     * <p>For any given constraint, there must be a clear delineation
     * of which aspects (if any) must be implemented by the transport
     * layer.  This method must not return a constraint (as a
     * requirement or a preference, directly or as an element of
     * another constraint) unless this instance can implement all of
     * those aspects.  Also, this method must not return a constraint
     * for which all aspects must be implemented by the transport
     * layer.  Most of the constraints in the {@link
     * net.jini.core.constraint} package must be fully implemented by
     * the transport layer and thus must not be returned by this
     * method; the one exception is {@link Integrity}, for which the
     * transport layer is responsible for the data integrity aspect
     * and higher layers are responsible for the code integrity
     * aspect.
     *
     * <p>For any {@link ConstraintAlternatives} in the specified
     * constraints, this method should only return a corresponding
     * constraint if all of the alternatives supported by this
     * instance need to be at least partially implemented by higher
     * layers in order to be fully satisfied.
     *
     * <p>The constraints passed to this method may include
     * constraints based on relative time.
     *
     * @param constraints the constraints that must be supported
     *
     * @return the constraints that must be at least partially
     * implemented by higher layers
     *
     * @throws UnsupportedConstraintException if the transport layer
     * aspects of any of the specified requirements are not supported
     * by this instance (either in general or in the current security
     * context)
     *
     * @throws SecurityException if the current security context does
     * not have the permissions necessary to perform this operation
     *
     * @throws NullPointerException if <code>constraints</code> is
     * <code>null</code>
     **/
    InvocationConstraints checkConstraints(InvocationConstraints constraints)
	throws UnsupportedConstraintException;
}
