/*
 *  Licensed to the Apache Software Foundation (ASF) under one
 *  or more contributor license agreements.  See the NOTICE file
 *  distributed with this work for additional information
 *  regarding copyright ownership.  The ASF licenses this file
 *  to you 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.apache.openaz.pepapi;

import java.util.List;

/**
 * Serves as the main entry point into the PepAPI framework. It coordinates authorization request creation,
 * execution and response assemblage. Applications typically work with a single instance of PepAgent which is
 * thread-safe. The <code>decide()</code> method, which provides the most general mechanism for authorization,
 * accepts a collection of application Domain Objects, each with it's own <code>ObjectMapper</code> defined.
 * The client application thus passes these Domain Objects directly, <code>decide()</code> uses reflection to
 * determine their type, and then finds a type-specific mapper. This mechanism relies on application defined
 * library of Object Mappers, one for each Domain Object that the client program expects to use in an
 * authorization call. It is important to note that Java Primitives/Wrappers and other standard types(except
 * Collections) are not supported out of the box. This is primarily because there is no sensible default
 * mapping between a Java Standard Type and a XACML category and hence it's impossible for the framework to
 * make a mapping decision at runtime. However, client applications may enforce their own rules as they see
 * fit by providing Custom ObjectMapper(s) for these types. <code>simpleDecide()</code> method addresses the
 * simplest of use cases where attributes involved are simple userId, actionId and resourceId Strings.
 * <code>bulkDecide()</code> provides an abstraction for a MultiRequest, where in client applications may
 * provide collection of Domain Object bindings/associations each of which map to individual requests. The
 * method separates out Domain Object associations with multiple cardinality from the ones shared across
 * requests. Thus, in a <code>bulkDecide()</code> call applications provide two sets of arguments: - a List of
 * Domain Object bindings, each of which map to an individual request. - a collection of common Domain Objects
 * shared across all requests. Specific AzService implementations(PDP Providers) may implement bulkDecide() as
 * a XACML MultiRequest (Note: XACML Multi Decision Profile is optional) or as individual requests executed
 * iteratively.
 */
public interface PepAgent {

    /**
     * Returns a authorization decision for the given subjectId, actionId, resourceId Strings.
     *
     * @param subjectId
     * @param actionId
     * @param resourceId
     * @return
     * @throws PepException - if an appropriate ObjectMapper cannot be found. - if the underlying AzService
     *             instance/PDP throws an exception - if the PepAgent is configured to throw PepExceptions for
     *             "Indeterminate" or "Not Applicable" decisions.
     * @throws IllegalArgumentException if any of the arguments are null
     */
    PepResponse simpleDecide(String subjectId, String actionId, String resourceId);

    /**
     * Returns an authorization decision for the given collection of Domain Objects each with it's own
     * ObjectMapper instance. Java Primitives/Wrappers or other Standard types (except Collections) are not
     * supported out of the box. However, client applications may enforce their own rules as they see fit by
     * providing Custom ObjectMapper(s) for these types.
     *
     * @param objects
     * @return
     * @throws PepException - if an appropriate ObjectMapper cannot be found. - if the underlying AzService
     *             instance/PDP throws an exception - if the PepAgent is configured to throw PepException for
     *             "Indeterminate" or "Not Applicable" decisions.
     * @throws IllegalArgumentException if any of the arguments are null
     */
    PepResponse decide(Object... objects);

    /**
     * Returns a PepResponse instance representing a collection of decisions, each of which corresponds to an
     * association. Each association represents a specific instance of Domain Object binding. A typical
     * example for an association would be an Action-Resource pair.
     *
     * @param associations a list of Domain Object bindings, each of which maps to a individual Request.
     * @param objects a collection of common Domain Objects shared across all Requests.
     * @return
     * @throws PepException - if an appropriate ObjectMapper cannot be found. - if the underlying AzService
     *             instance/PDP throws an exception - if the PepAgent is configured to throw PepExceptions for
     *             "Indeterminate" or "Not Applicable" decisions.
     * @throws IllegalArgumentException if any of the arguments are null
     */
    List<PepResponse> bulkDecide(List<?> associations, Object... objects);

}