resin-ioc.xtp

RESIN 3.2 最新源码

  <th>Description</th>
</tr>
<tr>
  <td>getContextData</td>
  <td>Returns a map containing any context information</td>
</tr>
<tr>
  <td>getMethod</td>
  <td>Returns the called API method</td>
</tr>
<tr>
  <td>getParameters</td>
  <td>Returns the Java parameters for the call</td>
</tr>
<tr>
  <td>getTarget</td>
  <td>Returns the target object, i.e. the Java object that will
receive the call after all the interceptors complete.</td>
</tr>
<tr>
  <td>proceed</td>
  <td>Call the next interceptor in the chain, or call the final object
at the end of the chain.</td>
</tr>
<tr>
  <td>setParameters</td>
  <td>Sets the Java parameters for the call</td>
</tr>
</deftable>

<def title="javax.interceptor.InvocationContext">
public interface InvocationContext {
  public Object proceed() throws Exception;

  public Map&lt;String, Object> getContextData();
  public Method getMethod();
  public Object[] getParameters() throws IllegalStateException;
  public void setParameters(Object[] parameters) throws IllegalStateException;
  public Object getTarget();
}
</def>
</s2>

<s2 title="@PermitAll">

<p><code>@PermitAll</code> annotation marks a method as allowed for all
users.</p>

<def title="javax.annotation.security.PermitAll">
@Target({METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface PermitAll {
}
</def>
</s2>

<s2 title="@RolesAllowed">

<p><code>@RolesAllowed</code> lists all the roles (i.e. permissions) allowed
to access the method.  If the user in the security context does not match
the role, an exception will be thrown.</p>

<deftable title="RolesAllowed properties">
<tr>
  <th>Value</th>
  <th>Meaning</th>
  <th>Default</th>
</tr>
<tr>
  <td>value</td>
  <td>Lists the roles (permissions) that are allowed.</td>
</tr>
</deftable>

<def title="javax.annotation.security.RolesAllowed">
@Target({TYPE,METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface RolesAllowed {
  String []value();
}
</def>
</s2>

<s2 title="@RunAs">

<p><code>@RunAs</code> changes the security context user to a defined
role.  Security tests within the context of the <code>@RunAs</code> will
match the specified role.</p>

<deftable title="RunAs properties">
<tr>
  <th>Value</th>
  <th>Meaning</th>
  <th>Default</th>
</tr>
<tr>
  <td>value</td>
  <td>The role name to run as.</td>
</tr>
</deftable>

<def title="javax.annotation.security.RunAs">
@Target({TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface RunAs {
  String value();
}
</def>
</s2>

<s2 title="@TransactionAttribute">

<p>Defines the transaction boundary for business methods.  The
default value is REQUIRED.  If @TransactionAttribute annotates the class,
it defines the default value. </p>

<p>All Resin-managed beans can use <code>@TransactionAttribute</code>:
@Stateful, @Stateless, @MessageDriven and plain Java beans.</p>

<deftable title="TransactionAttributeType">
<tr>
  <th>Value</th>
  <th>Meaning</th>
</tr>
<tr>
  <td>REQUIRED</td>
  <td>Start a new transaction if necessary</td>
</tr>
<tr>
  <td>SUPPORTS</td>
  <td>Don't start a new transaction, but use one if it exists</td>
</tr>
<tr>
  <td>MANDATORY</td>
  <td>Require the caller to have started a transaction</td>
</tr>
<tr>
  <td>NEVER</td>
  <td>Forbid the caller to have started a transaction</td>
</tr>
<tr>
  <td>REQUIRESNEW</td>
  <td>Always start a new transaction, suspending the old one</td>
</tr>
<tr>
  <td>NOTSUPPORTED</td>
  <td>Suspend any active transaction</td>
</tr>
</deftable>

<ul>
<li>SUPPORTS is typically used for read-only methods</li>
<li>REQUIRED is typically used for updating (read/write) methods</li>
</ul>

<def title="javax.ejb.TransactionAttribute">
@Target({TYPE,METHOD})
@Retention(RUNTIME)
public @interface TransactionAttribute {
  TransactionAttributeType value() default REQUIRED;
}
</def>

</s2>

</s1>

<s1 title="Dependency Injection Annotations">

<s2 title="@BindingType" type="defun">

<p><code>@BindingType</code> is a meta-annotation for creating custom
injection binding types.  Applications can create their own injection
annotations like <code>@Named</code> to provide application-specific
binding.  For example, a database might have a <code>@XA</code>
and a <code>@NonXA</code> connector implemented.</p>

<def title="javax.webbeans.BindingType">
@Target({TYPE})
@Retention(RUNTIME)
public @interface BindingType {
}
</def>

<example title="Example: custom @XA binding type">
package demo;

@BindingType
@Target({TYPE, METHOD, FIELD, PARAMETER})
@Retention(RUNTIME)
public @interface XA {
}
</example>

<example title="Example: using the custom @XA binding type">
package demo;

import javax.sql.*;

public class MyBean {
  @XA DataSource _xa;
  @NonXA DataSource _nonXa;

  ...
}
</example>

</s2>

<s2 title="@EJB" type="defun">

<p>Configures EJB values for a field or method.</p>

<p>@EJB is essentially a @Resource where it's known that the
result is an EJB interface.</p>

<deftable-childtags>
<tr>
  <th>Property</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>businessInterface</td>
  <td>The EJB interface to lookup</td>
  <td>The field type</td>
</tr>
<tr>
  <td>name</td>
  <td>The EJB name of the resource</td>
  <td>The field name</td>
</tr>
<tr>
  <td>jndiName</td>
  <td>The jndi name of the resource</td>
  <td>The EJB name</td>
</tr>
</deftable-childtags>

<def title="javax.ejb.EJB">
@Target({TYPE, METHOD, FIELD, PARAMETER})
@Retention(RUNTIME)
public @interface EJB {
  String name() default "";
  String businessInterface() default "";
  String jndiName() default "";
}
</def>

<p>In the following exaple, Resin will call <code>setFoo</code>
method with the bean in "java:comp/env/ejb/foo" before the
session is started.</p>

<example title="Example: @EJB method injection">
@EJB
void setFoo(example.Test test)
{
  _test = test;
}
</example>

</s2>

<s2 title="@In" type="defun">

<p>Marks a field, method, or parameter for injection.
When used with a constructor, it marks the given constructor as
the constructor to use when creating new instances.</p>

<def title="javax.webbeans.In">
@Target({CONSTRUCTOR, METHOD, FIELD, PARAMETER, TYPE})
@Retention(RUNTIME)
public @interface In {
}
</def>
</s2>

<s2 title="@Named" type="defun">

<p><code>@Named</code> is a predefined <code>@BindingType</code>
annotation for named objects.  Many application objects can just use
<code>@Named</code> to disambiguate multiple objects with the same
type.
</p>

<deftable title="@Named parameters">
<tr>
  <th>Property</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>value</td>
  <td>The name binding for the object to inject</td>
  <td>required</td>
</tr>
</deftable>

<def title="javax.webbeans.Named">
@BindingType
@Target({METHOD, FIELD, PARAMETER, TYPE})
@Retention(RUNTIME)
public @interface Named {
  String value();
}
</def>
</s2>

<s2 title="@New" type="defun">

<p>Marks a field, method, or parameter for injection with a new
instance of the object.  If the type of the <code>@New</code>
has not yet been registered with the WebBeans directory, it will
be registered automatically..</p>

<def title="javax.webbeans.New">
@Target({METHOD, FIELD, PARAMETER, TYPE})
@Retention(RUNTIME)
public @interface New {
}
</def>
</s2>

<s2 title="@NonBinding" type="defun">

<p><code>@NonBinding</code> is a meta-annotation used for
creating <code>@BindingType</code> annotations.   It excludes an
annotation property from the binding algorithm.  Normally, the
injection binding must matches all the propeties in the object's
annotations with the properties in the injection property.  The
<code>@NonBinding</code> annotation skips the check for the annotated
property.
</p>

<def title="javax.webbeans.NonBinding">
@Target({FIELD, METHOD})
@Retention(RUNTIME)
public @interface NonBinding {
}
</def>

<example title="Example: @Demo with @NonBinding">
package demo;

@BindingType
@Target({TYPE, METHOD, FIELD, PARAMETER})
@Retention(RUNTIME)
public @interface Demo {
  @NonBinding String description() default "";
}
</example>

</s2>

<s2 title="@Resource" type="defun">

<p><code>@Resource</code> provides JNDI-based resource injection.
<code>@Resource</code> can also be used at the Class level to
declare a dependency in cases where the session bean loads the
JNDI value by itself.</p>

<p>In general, it's better to use the WebBeans
annotations: <code>@In</code>, <code>@Named</code>
or custom <code>@BindingType</code> annotations, since they use the
type-safe WebBeans registry instead of JNDI.  <code>@Resource</code>
is supported for backwards compatibility.</p>

<deftable-childtags>
<tr>
  <th>Property</th>
  <th>Description</th>
  <th>Default</th>
</tr>
<tr>
  <td>authenticationType</td>
  <td>What kind of authentication is expected for the resource: APPLICATION or
CONTAINER</td>
  <td>CONTAINER</td>
</tr>
<tr>
  <td>description</td>
  <td>An optional description of the resource</td>
  <td></td>
</tr>
<tr>
  <td>name</td>
  <td>The jndi-name of the resource</td>
  <td>java:comp/env/<var>class-name</var>#<var>field-name</var></td>
</tr>
<tr>
  <td>type</td>
  <td>The class of the expected resource</td>
  <td>The field type</td>
</tr>
<tr>
  <td>shareable</td>
  <td>True if the bean follows JCA shareability requirements.</td>
  <td>true</td>
</tr>
<tr>
  <td>mappedName</td>
  <td>The produce-specific name of the resource</td>
  <td>The field name</td>
</tr>
</deftable-childtags>

</s2>

</s1>

<s1 title="Framework Integration">

<p>Frameworks like Struts2, Wicket, and Mule can delegate object creation
to Resin-IoC.  By configuration Resin-IoC to create the framework
objects, your application's components can directly inject Resin resources
and application components configured with Resin.</p>

<p>Integration information for the frameworks is maintained on the
Caucho wiki site.  Currently supported frameworks include:</p>

<ul>
<li><a href="http://wiki.caucho.com/Mule">http://wiki.caucho.com/Mule</a></li>
<li><a href="http://wiki.caucho.com/Spring">http://wiki.caucho.com/Spring</a></li>
<li><a href="http://wiki.caucho.com/Struts2">http://wiki.caucho.com/Struts2</a></li>
<li><a href="http://wiki.caucho.com/Wicket">http://wiki.caucho.com/Wicket</a></li>
</ul>

<p>Implementing new object factories for other frameworks is straightforward.
</p>

<s2 title="ObjectFactory pattern">

<p>Frameworks like Struts2 provide an <code>ObjectFactory</code> pattern.
In this case, the framework gives a <code>Class</code> object and asks
the factory to create a new instance.  The <code>ObjectFactory</code> is
the most powerful pattern, since objects can use @Observes, @InterceptionType,
@TransactionAttribute and even @Stateless, as well as the usual dependency
injection.</p>

<example title="Example: Struts2 integration">
package com.caucho.xwork2;

import com.caucho.webbeans.manager.*;
import com.opensymphony.xwork2.ObjectFactory;
import java.util.*;
import javax.webbeans.*;

public class ResinObjectFactory extends ObjectFactory
{
  private final WebBeansContainer _webBeans = WebBeansContainer.create();
  
  @Override
  public Object buildBean(Class clazz, Map extraContext)
    throws Exception
  {
    return _webBeans.getObject(clazz);
  }
}
</example>

</s2>

<s2 title="Injection pattern">

<p>Some frameworks, like Wicket, prefer to instantiate the object, but
can call Resin-IoC for a dependency-injection step.  With this kind of
framework integration, the created object only gets dependency-injection;
it does not get any aspects or interception.</p>

<example title="Example: Wicket injection">
package com.caucho.wicket;

import com.caucho.webbeans.manager.*;

import org.apache.wicket.Component;
import org.apache.wicket.application.*;

public class ResinComponentInjector implements IComponentInstantiationListener
{
  private WebBeansContainer _webBeans = WebBeansContainer.create();
  
  public void onInstantiation(Component component)
  {
    _webBeans.injectObject(component);
  }
}
</example>

</s2>

</s1>

</body>
</document>