resin-ioc.xtp

RESIN 3.2 最新源码

<p>Setters taking a <code>List</code> or array argument can be configured
with list values.</p>

<p>List items are specified directly with &lt;value> elements.  There is
no extra &lt;list> element required.  The &lt;list> element is only used
when creating a sub-list or sub-element (see below.)</p>

<example title="Example: MyBean.setValues(List)">
&lt;my-bean>
  &lt;values>
    &lt;value>a&lt;/value>
    &lt;value>b&lt;/value>
    &lt;value>c&lt;/value>
  &lt;/values>
&lt;/my-bean>
</example>

<example title="Example: MyBean.setValues(String [])">
&lt;my-bean>
  &lt;values>
    &lt;value>a&lt;/value>
    &lt;value>b&lt;/value>
    &lt;value>c&lt;/value>
  &lt;/values>
&lt;/my-bean>
</example>

<p>In the following example, the argument is an object, so we need
a &lt;list> element to tell Resin to create a list.  The object
created will be an <code>ArrayList</code>.</p>
<example title="Example: MyBean.setValues(Object)">
&lt;my-bean>
  &lt;values>
    &lt;list>
      &lt;value>a&lt;/value>
      &lt;value>b&lt;/value>
      &lt;value>c&lt;/value>
    &lt;/list>
  &lt;/values>
&lt;/my-bean>
</example>

<p>Resin-IoC can always use the <code>addXXX</code> pattern to add
a variable number of items.  Normally, the <code>addXXX</code> pattern
is easier and more maintainable than the <code>addList</code> pattern.
In particular, validation of the item values is quicker and more accurate
with <code>addXXX</code>.</p>

<example title="Example: MyBean.addValue(String)">
&lt;my-bean>
  &lt;value>a&lt;/value>
  &lt;value>b&lt;/value>
  &lt;value>c&lt;/value>
&lt;/my-bean>
</example>

</s3>

<s3 title="map">

<p>Generic maps can use an &lt;entry> syntax to define property values.</p>

<example title="Example: MyBean.setValues(Map)">
&lt;my-bean>
  &lt;values>
    &lt;entry key="a" value="one"/>
    &lt;entry key="b" value="two"/>
    &lt;entry key="c" value="three"/>
  &lt;/values>
&lt;/my-bean>
</example>

</s3>

</s2>

<s2 title="References and EL Expressions">

<p>Resin-IoC configuration files can use EL expressions to get references
to resources, beans, system properties, and calculate generatal expressions
based on those values.  Since all Resin's resources are added to
the WebBeans registry automatically, application components have access to
anything they need.</p>

<p>Both the JSP immediate syntax and deferred syntax are
supported (${...} vs #{...}).  Currently, there is no distinction
between the two, but the deferred syntax is preferred, since Resin-IoC
initializes beans lazily to handle circular references.</p>

<example title="Example: circular references in resin-web.xml">
&lt;web-app xmlns="http://caucho.com/ns/resin">

  &lt;bean name="a" class="qa.FooBean">
    &lt;init bar="#{b}"/>
  &lt;/bean>

  &lt;bean name="b" class="qa.BarBean">
    &lt;init foo="#{a}"/>
  &lt;/bean>

&lt;/web-app>
</example>

<p>Because Resin's EL implementation allows method expressions, you can
use beans as factories in the EL expressions.</p>

</s2>

</s1>

<s1 title="Scripting: PHP, JSF and JSP">

<p>If your application is using a scripting language like PHP for the
presentation layer, the WebBeans registry provides a simple interface to
use your components and services.  Although WebBeans injection is typed,
each WebBean is also registered under its name for scripting applications.
The name must be globally unique, of course, unlike the typed injection
binding.</p>

<p>The default scripting name is the name of the component's class, with
the first character lowercased.  You can change the name by adding
a <code>@Named</code> or setting a <code>name</code> attribute in the
<code>&lt;component></code> or <code>&lt;bean></code>.</p>

<example title="Example: Movie.java">
@Component
@RequestScoped
public class Movie {
  ...
}
</example>

<s2 title="Quercus/PHP">

<p>In Quercus/PHP, the <code>java_bean(name)</code> method returns the
component with the given name.  For singletons, Resin will return the unique
bean.  For other beans, Resin will create the bean if necessary and
store it in the configured scope.</p>

<example title="Example: accessing the movie from PHP">
&lt;?php

$movie = java_bean("movie");

echo "title: " . $movie->title . "\n";

?>
</example>

</s2>

<s2 title="JSP/JSF EL">

<p>Resin automatically provides the WebBeans variables to EL expressions
for both JSP and JSF.</p>

<example title="Example: accessing the movie from JSP">
&lt;c:out value="${movie.title}"/>
</example>

<p>The JSF also uses the expression language, but uses the deferred syntax,
since JSF needs to build a component tree first.</p>

<example title="Example: accessing the movie from JSF">
&lt;f:view>
  &lt;h:outputText value="#{movie.title}"/>
&lt;/f:view>
</example>

</s2>

</s1>

<s1 title="@BindingType: custom injection binding">

<p>Although many applications will just use <code>@In</code> and
<code>@Named</code> injection binding, applications can create their
own binding annotations.  Some bindings might be more
logical, for example an <code>@XA</code> annotation might mark the
transactional <code>DataSource</code>, while <code>@ReadOnly</code> might
mark a read-only <code>DataSource</code>.  Drivers might
use <code>Scheme("mysql")</code> to allow for URL-based configuration,
like the "jdbc:mysql://localhost:3306/test" of JDBC.</p>

<example title="Example: ReadOnly and XA databases">
import com.foo.webbeans.ReadOnly;
import com.foo.webbeans.XA;

public class MyServlet extends GenericServlet {
  @ReadOnly DataSource _readDatabase;
  @XA DataSource _xaDatabase;

  ...
}
</example>

<p>You can create a custom binding annotation using
the <code>@BindingType</code> annotation.  When Resin introspects the
injection point and the components, it will look for any annotation
with the <code>@BindingType</code> meta-annotation.</p>

<p>The annotation can also have annotation parameters.  If they exist,
Resin will make sure only matching components will be injected.</p>

<p>The custom binding annotation can be used anywhere predefined
binding annotations can, including fields, methods, constructor,
producers, or event observers.</p>

<example title="Example: ReadOnly.java">
package com.foo.webbeans;

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

</s1>

<s1 title="@Produces methods">

<p>Some components are more easily produced using a factory method rather
than getting instantiated directly.  In those cases, your application
can mark a factory component's method with the <code>@Produces</code>
annotation.  Resin will register the results of the method with WebBeans.</p>

<example title="Example: @Produces">
import javax.webbeans.Component;
import javax.webbeans.Produces;
import com.caucho.webbeans.Singleton;

@Component
@Singleton
public class MyFactory {
  @Produces public List&lt;Movie> currentMovies()
  {
    ...
  }
</example>

<p>The produces method can be marked with <code>@ScopeType</code>,
<code>@ComponentType</code> or <code>@BindingType</code> annotations just
like a class-based component can.</p>

</s1>

<s1 title="Aspects: Method Interception">

<p>Some functions like security, logging and transaction handing need
to be used for each method invidually, but require a common
implementation pattern.  The WebBeans AOP uses a single method as
a interceptor for each method invocation.</p>

<p>Your method will use an <code>@InterceptorType</code> annotation
letting Resin know where it should apply the interceptor:</p>

<example title="Example: secure method">
import com.foo.webbeans.Secure;

@Component
public class MyBean {
  @Secure
  public void doSomethingSafely() { ... }
}
</example>

<p>The implementation class will use the
<code>javax.interceptor.*</code> API to implement the
interceptor.</p>

<example title="Example: security implementation">
import javax.interceptor.*;
import javax.webbeans.Interceptor;

@Secure @Interceptor
public class MySecureInterceptor {
  @AroundInvoke
  public Object checkSecurity(InvocationContext inv) throws Exception
  {
    if (! myContextIsSecure())
      throw new MySecurityException("permissiong denied");

    return inv.proceed();
  }
}
</example>

<p>The interceptors must be enabled in the
<code>META-INF/web-beans.xml</code> file.  This protects your code
from any surprising interceptors.</p>

<example title="Example: META-INF/web-beans.xml">
&lt;web-beans xmlns="http://caucho.com/ns/resin">
  &lt;interceptors>
    &lt;interceptor>com.foo.MySecureInterceptor&lt;/interceptor>
  &lt;/interceptors>
&lt;/web-beans>
</example>

</s1>

<s1 title="Event Handling">

<p>Your components can also handle events thrown through the WebBeans API.
Any method with an <code>@Observes</code> parameter will receive events
with the proper type.  The event can be any Java class.</p>

<example title="Example: event handler">
import javax.webbeans.Component;
import javax.webbeans.Observes;

@Component
public class MyHandler {
  public void myHandlerMethod(@Observes Movie movie)
  {
    ...
  }
}
</example>

<p>Your application can throw events through the WebBeans
<code>Container</code> API, which is available through injection:</p>

<example title="Example: raising events">
import javax.webbeans.Container;

public void MyServlet extends GenericServlet {
  @In Container _webbeans;

  public void service(ServletRequest req, ServletResponse res)
  {
    _webbeans.raiseEvent(new Movie("A Bridge Too Far"));
  }
}
</example>

<p>For the above example, Resin will look for all components which
have an <code>@Observes</code> method receiving a <code>Movie</code>
and deliver the event to that component.</p>

</s1>


<s1 title="Aspect Annotations">

<s2 title="@AroundInvoke">

<p><code>@AroundInvoke</code> marks an interception method on the
bean or an interceptor class.  The interceptor is invoked while
processing a business method.</p>

<def title="javax.interceptor.AroundInvoke">
@Target(METHOD)
@Retention(RUNTIME)
public @interface AroundInvoke {
}
</def>

<example title="Example: @AroundInvoke method">
import javax.interceptor.*;

public class MyBean {
  @AroundInvoke
  protected Object log(InvocationContext cxt)
    throws Exception
  {
    System.out.println("Before: " + cxt.getMethod());

    Object value = cxt.proceed();

    System.out.println("After: " + cxt.getMethod());

    return value;
  }

  public String hello()
  {
    return "hello, world";
  }
}
</example>

</s2>

<s2 title="@DenyAll">

<p><code>@DenyAll</code> annotation marks a method as forbidden to all
users.</p>

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

<s2 title="@Interceptor">

<p><code>@Interceptor</code> marks a class as an interceptor using
WebBeans-style interception.  The class will normally also have
an <code>@AroundInvoke</code> method as well as any
<code>InterceptorBindingType</code> annotations.</p>

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

</s2>

<s2 title="@InterceptorBindingType">

<p><code>@InterceptorBindingType</code> is a WebBeans meta-annotation for
creating interceptor binding types.  Applications will use
<code>@InterceptorBindingType</code> to create application-specific
interceptors.  The WebBeans-style of interception decouples the
interception declaration from the interceptor classes, in contrast
with the EJB-style which specifies the interceptor class directly.</p>

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

</s2>

<s2 title="@Interceptors">

<p><code>@Interceptors</code> marks an method or class as being
intercepted by the named classes.  The interceptor classes will
implement an <code>@AroundInvoke</code> method to process the
<code>InvocationContext</code>.</p>

<deftable title="@Interceptors properties">
<tr>
  <th>Value</th>
  <th>Meaning</th>
  <th>Default</th>
</tr>
<tr>
  <td>value</td>
  <td>Lists the interceptor classes to apply to the method.</td>
</tr>
</deftable>

<def title="javax.interceptor.Interceptors">
@Target({TYPE,METHOD})
@Retention(RUNTIME)
public @interface Interceptors {
  public Class []value();
}
</def>

<example title="Example: @Interceptor method">
import javax.interceptor.*;

public class MyBean {
  @Interceptors(MyInterceptor.class)
  public String hello()
  {
    return "hello, world";
  }
}

public class MyInterceptor {
  @AroundInvoke
  protected Object log(InvocationContext cxt)
    throws Exception
  {
    System.out.println("Before: " + cxt.getMethod());

    Object value = cxt.proceed();

    System.out.println("After: " + cxt.getMethod());

    return value;
  }
}
</example>

</s2>

<s2 title="InvocationContext">

<p>The <code>InvocationContext</code> API is used by invocation
methods to examine the calling context, and possibly set parameters.
A no-op interceptor would just call the <code>proceed()</code> method.</p>

<deftable title="InvocationContext methods">
<tr>
  <th>Method</th>