001: /*
002: * JBoss, Home of Professional Open Source.
003: * Copyright 2006, Red Hat Middleware LLC, and individual contributors
004: * as indicated by the @author tags. See the copyright.txt file in the
005: * distribution for a full listing of individual contributors.
006: *
007: * This is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU Lesser General Public License as
009: * published by the Free Software Foundation; either version 2.1 of
010: * the License, or (at your option) any later version.
011: *
012: * This software is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public
018: * License along with this software; if not, write to the Free
019: * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021: */
022: package javax.ejb;
023:
024: import javax.transaction.UserTransaction;
025:
026: import java.security.Identity;
027: import java.security.Principal;
028: import java.util.Properties;
029:
030: /**
031: * <P>The EJBContext interface provides an instance with access to the
032: * container-provided runtime context of an enterprise Bean instance.</P>
033: * <P>This interface is extended by the SessionContext and EntityContext
034: * interface to provide additional methods specific to the enterprise
035: * Bean type.</P>
036: *
037: * @version $Revision: 57196 $
038: */
039: public interface EJBContext {
040:
041: /**
042: * Obtain the enterprise bean's remote home interface.
043: *
044: * @return The enterprise bean's remote home interface.
045: * @throws java.lang.IllegalStateException
046: * - if the enterprise bean does not have a remote home interface.
047: */
048: public EJBHome getEJBHome();
049:
050: /**
051: * Obtain the enterprise bean's local home interface.
052: *
053: * @return The enterprise bean's local home interface.
054: * @throws java.lang.IllegalStateException
055: * - if the enterprise bean does not have a local home interface.
056: */
057: public EJBLocalHome getEJBLocalHome();
058:
059: /**
060: * <B>Deprecated.</B> <I>Use the JNDI naming context java:comp/env to access enterprise bean's environment.</I>
061: * <p/>
062: * <P>Obtain the enterprise bean's environment properties.</P>
063: * <p/>
064: * <P><B>Note:</B> If the enterprise bean has no environment properties this method returns an empty
065: * java.util.Properties object. This method never returns null.</P>
066: *
067: * @return The environment properties for the enterprise bean.
068: */
069: public Properties getEnvironment();
070:
071: /**
072: * <B>Deprecated.</B> <I>Use Principal getCallerPrincipal() instead.</I>
073: * <p/>
074: * <P>Obtain the java.security.Identity of the caller. This method is deprecated in EJB 1.1.
075: * The Container is allowed to return alway null from this method. The enterprise bean should use
076: * the getCallerPrincipal method instead.</P>
077: *
078: * @return The Identity object that identifies the caller.
079: */
080: public Identity getCallerIdentity();
081:
082: /**
083: * Obtains the java.security.Principal of the caller.
084: *
085: * @return The Principal object that identifies the caller. This method never returns null.
086: */
087: public Principal getCallerPrincipal();
088:
089: /**
090: * <B>Deprecated.</B> <I>Use boolean isCallerInRole(String roleName) instead.</I>
091: * <p/>
092: * <P>Test if the caller has a given role.</P>
093: * <p/>
094: * <P>This method is deprecated in EJB 1.1. The enterprise bean should use the
095: * isCallerInRole(String roleName) method instead.</P>
096: *
097: * @param role - The java.security.Identity of the role to be tested.
098: * @return True if the caller has the specified role.
099: */
100: public boolean isCallerInRole(Identity role);
101:
102: /**
103: * Tests if the caller has a given role.
104: *
105: * @param roleName - The name of the security role. The role must be one of the security roles that
106: * is defined in the deployment descriptor.
107: * @return True if the caller has the specified role.
108: */
109: public boolean isCallerInRole(String roleName);
110:
111: /**
112: * Obtain the transaction demarcation interface. Only enterprise beans with bean-managed transactions
113: * are allowed to to use the UserTransaction interface. As entity beans must always use container-managed
114: * transactions, only session beans with bean-managed transactions are allowed to invoke this method.
115: *
116: * @return The UserTransaction interface that the enterprise bean instance can use for transaction demarcation.
117: * @throws java.lang.IllegalStateException
118: * - The Container throws the exception if the instance is not
119: * allowed to use the UserTransaction interface (i.e. the instance is of a bean with container-managed
120: * transactions).
121: */
122: public UserTransaction getUserTransaction()
123: throws IllegalStateException;
124:
125: /**
126: * Mark the current transaction for rollback. The transaction will become permanently marked for rollback.
127: * A transaction marked for rollback can never commit. Only enterprise beans with container-managed
128: * transactions are allowed to use this method.
129: *
130: * @throws java.lang.IllegalStateException
131: * - The Container throws the exception if the instance is not
132: * allowed to use this method (i.e. the instance is of a bean with bean-managed transactions).
133: */
134: public void setRollbackOnly() throws IllegalStateException;
135:
136: /**
137: * Test if the transaction has been marked for rollback only. An enterprise bean instance can use
138: * this operation, for example, to test after an exception has been caught, whether it is fruitless
139: * to continue computation on behalf of the current transaction. Only enterprise beans with
140: * container-managed transactions are allowed to use this method.</P>
141: *
142: * @return True if the current transaction is marked for rollback, false otherwise.
143: * @throws java.lang.IllegalStateException
144: * - The Container throws the exception if the instance
145: * is not allowed to use this method (i.e. the instance is of a bean with bean-managed transactions).
146: */
147: public boolean getRollbackOnly() throws IllegalStateException;
148:
149: /**
150: * Get access to the EJB Timer Service.
151: *
152: * @throws IllegalStateException The Container throws the exception
153: * if the instance is not allowed to use this method (e.g. if the bean
154: * is a stateful session bean)
155: */
156: public TimerService getTimerService() throws IllegalStateException;
157:
158: /**
159: * New from EJB 3.0. A JNDI lookup method that doesn't throw exceptions
160: *
161: * @param name
162: * @return returns null if JNDI lookup finds nothing
163: */
164: public Object lookup(String name);
165: }
|