001/**
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003 *
004 * Copyright (c) 2006 Sun Microsystems Inc. All Rights Reserved
005 *
006 * The contents of this file are subject to the terms
007 * of the Common Development and Distribution License
008 * (the License). You may not use this file except in
009 * compliance with the License.
010 *
011 * You can obtain a copy of the License at
012 * https://opensso.dev.java.net/public/CDDLv1.0.html or
013 * opensso/legal/CDDLv1.0.txt
014 * See the License for the specific language governing
015 * permission and limitations under the License.
016 *
017 * When distributing Covered Code, include this CDDL
018 * Header Notice in each file and include the License file
019 * at opensso/legal/CDDLv1.0.txt.
020 * If applicable, add the following below the CDDL Header,
021 * with the fields enclosed by brackets [] replaced by
022 * your own identifying information:
023 * "Portions Copyrighted [year] [name of copyright owner]"
024 *
025 * $Id: Request.java,v 1.2 2008/06/25 05:48:11 qcheng Exp $
026 *
027 */
028
029package com.sun.identity.xacml.context;
030
031import com.sun.identity.xacml.common.XACMLException;
032
033import java.util.List;
034
035/**
036 * The <code>Request</code> element is the top-level element in the XACML
037 * context scehema. Its an abstraction layer used by the policy language.
038 * It contains <code>Subject</code>, <code>Resource</code>, <code>Action
039 * </code> and <code>Environment<code> elements.
040 * <p>
041 * <pre>
042 * &lt;xs:complexType name="RequestType">
043 *   &lt;xs:sequence>
044 *     &lt;xs:element ref="xacml-context:Subject" maxOccurs="unbounded"/>
045 *     &lt;xs:element ref="xacml-context:Resource" maxOccurs="unbounded"/>
046 *     &lt;xs:element ref="xacml-context:Action"/>
047 *     &lt;xs:element ref="xacml-context:Environment"/>
048 *   &lt;xs:sequence>
049 * &lt;xs:complexType>
050 * </pre>
051 *@supported.all.api
052 */
053public interface Request {
054
055    /**
056     * Returns the one to many <code>Subject</code> elements of this object
057     *
058     * @return the <code>Subject</code> elements of this object
059     */
060    public List getSubjects();
061
062    /**
063     * Sets the one to many <code>Subject</code> elements of this object
064     *
065     * @param subjects the one to many <code>Subject</code> elements of this 
066     * object
067     *
068     * @exception XACMLException if the object is immutable
069     * An object is considered <code>immutable</code> if <code>
070     * makeImmutable()</code> has been invoked on it. It can
071     * be determined by calling <code>isMutable</code> on the object.
072     */
073    public void setSubjects(List subjects) throws XACMLException;
074
075    /**
076     * Returns the one to many <code>Resource</code> elements of this object
077     *
078     * @return the <code>Resource</code> elements of this object
079     */
080    public List getResources();
081
082    /**
083     * Sets the one to many <code>Resource</code> elements of this object
084     *
085     * @param resources the one to many <code>Resource</code> elements of this 
086     * object
087     *
088     * @exception XACMLException if the object is immutable
089     * An object is considered <code>immutable</code> if <code>
090     * makeImmutable()</code> has been invoked on it. It can
091     * be determined by calling <code>isMutable</code> on the object.
092     */
093    public void setResources(List resources) throws XACMLException;
094
095    /**
096     *
097     * Returns the instance of <code>Action</code>
098     *
099     * @return instance of <code>Action</code> 
100     */
101    public Action getAction();
102
103    /**
104     * Sets the instance of <code>Action</code>
105     *
106     * @param action instance of <code>Action</code> 
107     *
108     * @exception XACMLException if the object is immutable
109     * An object is considered <code>immutable</code> if <code>
110     * makeImmutable()</code> has been invoked on it. It can
111     * be determined by calling <code>isMutable</code> on the object.
112     */
113    public void setAction(Action action) throws XACMLException;
114
115    /**
116     * Returns the instance of <code>Environment</code>
117     *
118     * @return the instance of <code>Environment</code>
119     */
120    public Environment getEnvironment();
121
122    /**
123     * Sets the instance of <code>Environment</code>
124     *
125     * @param env instance of <code>Environment</code>
126     *
127     * @exception XACMLException if the object is immutable
128     * An object is considered <code>immutable</code> if <code>
129     * makeImmutable()</code> has been invoked on it. It can
130     * be determined by calling <code>isMutable</code> on the object.
131     */
132    public void setEnvironment(Environment env) throws XACMLException;
133
134   /**
135    * Returns a <code>String</code> representation of this object
136    * @param includeNSPrefix Determines whether or not the namespace qualifier
137    *        is prepended to the Element when converted
138    * @param declareNS Determines whether or not the namespace is declared
139    *        within the Element.
140    * @return a string representation of this object
141    * @exception XACMLException if conversion fails for any reason
142     */
143    public String toXMLString(boolean includeNSPrefix, boolean declareNS)
144            throws XACMLException;
145
146   /**
147    * Returns a string representation of this object
148    *
149    * @return a string representation of this object
150    * @exception XACMLException if conversion fails for any reason
151    */
152    public String toXMLString() throws XACMLException;
153
154   /**
155    * Makes the object immutable
156    */
157    public void makeImmutable();
158
159   /**
160    * Checks if the object is mutable
161    *
162    * @return <code>true</code> if the object is mutable,
163    *         <code>false</code> otherwise
164    */
165    public boolean isMutable();
166    
167}