View Javadoc

1   /* Copyright 2004 Acegi Technology Pty Limited
2    *
3    * Licensed under the Apache License, Version 2.0 (the "License");
4    * you may not use this file except in compliance with the License.
5    * You may obtain a copy of the License at
6    *
7    *     http://www.apache.org/licenses/LICENSE-2.0
8    *
9    * Unless required by applicable law or agreed to in writing, software
10   * distributed under the License is distributed on an "AS IS" BASIS,
11   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12   * See the License for the specific language governing permissions and
13   * limitations under the License.
14   */
15  
16  package org.acegisecurity;
17  
18  /***
19   * Reviews the <code>Object</code> returned from a secure object invocation,
20   * being able to modify the <code>Object</code> or throw an {@link
21   * AccessDeniedException}.
22   * 
23   * <p>
24   * Typically used to ensure the principal is permitted to access the domain
25   * object instance returned by a service layer bean. Can also be used to
26   * mutate the domain object instance so the principal is only able to access
27   * authorised bean properties or <code>Collection</code> elements. Often used
28   * in conjunction with an {@link org.acegisecurity.acl.AclManager} to
29   * obtain the access control list applicable for the domain object instance.
30   * </p>
31   * 
32   * <p>
33   * Special consideration should be given to using an
34   * <code>AfterInvocationManager</code> on bean methods that modify a database.
35   * Typically an <code>AfterInvocationManager</code> is used with read-only
36   * methods, such as <code>public DomainObject getById(id)</code>. If used with
37   * methods that modify a database, a transaction manager should be used to
38   * ensure any <code>AccessDeniedException</code> will cause a rollback of the
39   * changes made by the transaction.
40   * </p>
41   *
42   * @author Ben Alex
43   * @version $Id: AfterInvocationManager.java,v 1.2 2005/11/17 00:55:49 benalex Exp $
44   */
45  public interface AfterInvocationManager {
46      //~ Methods ================================================================
47  
48      /***
49       * Given the details of a secure object invocation including its returned
50       * <code>Object</code>, make an access control decision or optionally
51       * modify the returned <code>Object</code>.
52       *
53       * @param authentication the caller that invoked the method
54       * @param object the secured object that was called
55       * @param config the configuration attributes associated with the secured
56       *        object that was invoked
57       * @param returnedObject the <code>Object</code> that was returned from the
58       *        secure object invocation
59       *
60       * @return the <code>Object</code> that will ultimately be returned to the
61       *         caller (if an implementation does not wish to modify the object
62       *         to be returned to the caller, the implementation should simply
63       *         return the same object it was passed by the
64       *         <code>returnedObject</code> method argument)
65       *
66       * @throws AccessDeniedException if access is denied
67       */
68      public Object decide(Authentication authentication, Object object,
69          ConfigAttributeDefinition config, Object returnedObject)
70          throws AccessDeniedException;
71  
72      /***
73       * Indicates whether this <code>AfterInvocationManager</code> is able to
74       * process "after invocation" requests presented with the passed
75       * <code>ConfigAttribute</code>.
76       * 
77       * <p>
78       * This allows the <code>AbstractSecurityInterceptor</code> to check every
79       * configuration attribute can be consumed by the configured
80       * <code>AccessDecisionManager</code> and/or <code>RunAsManager</code>
81       * and/or <code>AfterInvocationManager</code>.
82       * </p>
83       *
84       * @param attribute a configuration attribute that has been configured
85       *        against the <code>AbstractSecurityInterceptor</code>
86       *
87       * @return true if this <code>AfterInvocationManager</code> can support the
88       *         passed configuration attribute
89       */
90      public boolean supports(ConfigAttribute attribute);
91  
92      /***
93       * Indicates whether the <code>AfterInvocationManager</code> implementation
94       * is able to provide access control decisions for the indicated secured
95       * object type.
96       *
97       * @param clazz the class that is being queried
98       *
99       * @return <code>true</code> if the implementation can process the
100      *         indicated class
101      */
102     public boolean supports(Class clazz);
103 }