See Also

Overview

Hello, World

EJB Models

Java

A Java bean is a multithreaded instance, e.g. a servlet or filter. Because it's multithreaded, application developers must take extra care to handle their own synchronization. In particular, threads must not store thread-specific data in Java bean fields and should generally avoid using static fields.

Java beans can use all the EJB and Resin-IoC aspects, including @TransactionAttribute, can use EJB @Interceptor classes, and Resin-Ioc @InterceptorBinding. They can handle events with the @Observes annotation, and add lifecycle callbacks with @PostConstruct and @PreDestroy.

@Local

The @Local annotation marks an interface of a bean as the exposed proxy API. Since @Stateless and @Stateful beans are proxy-based, they need an interface to expose to users of the bean. If the bean implements exactly in interface, it's chosen by default, otherwise the developer needs to mark the interface to export.

@Target(TYPE)
@Retention(RUNTIME)
public @interface Local {
  Class []value() default {};
}

@MessageDriven

MessageDriven beans receive messages from a Queue, using a pooled, single-threaded model like @Stateless beans.

See Resin messaging for more information.

The MessageDriven bean connects with the messaging provider through an ActivationSpec. For JMS, the activation spec specifies the JMS Queue.

@Target(TYPE)
@Retention(RUNTIME)
public @interface Stateful {
  String name() default "";
  Class messageListenerInterface() default Object.class;
  ActivationConfigProperty []activationConfig() default {};
  String mappedName() default "";
  String description() default "";
}

@Remote

The @Local annotation marks an interface of a bean as the exposed proxy API for remoting. See Resin remoting for more information on exposing beans as remote objects for protocols such as Hessian, Burlap, and SOAP.

@Target(TYPE)
@Retention(RUNTIME)
public @interface Remote {
  Class []value() default {};
}

SessionSynchronization

The SessionSynchronization interfaces tells Resin to enlist a @Stateful session bean in the current transaction. Before the transaction starts its commit processing, the bean will receive a callback message, allowing it to coordinate any data persistence. When the transaction either commits or rollsback, the bean will receive another callback indicating success or failure, allowing the bean to complete any transaction processing.

Only @Stateful session beans can implement SessionSynchronization because the bean itself will be registered with the transaction. The unique capability makes stateful session beans valuable for transaction processing.

public interface SessionSynchronization {
  public void afterBegin()
    throws EJBException, RemoteException;
  
  public void beforeCompletion()
    throws EJBException, RemoteException;
  
  public void afterCompletion(boolean committed)
    throws EJBException, RemoteException;
}

@Stateful

A stateful session bean is a single-threaded instance. Applications will need to create a new stateful instance for each thread or request.

@Target(TYPE)
@Retention(RUNTIME)
public @interface Stateful {
  String name() default "";
  String mappedName() default "";
  String description() default "";
}

@Stateless

A stateless session bean is a pooled proxy, where each request gets its own bean instance.

@Target(TYPE)
@Retention(RUNTIME)
public @interface Stateless {
  String name() default "";
  String mappedName() default "";
  String description() default "";
}

Aspect Annotations

@AroundInvoke

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

@Target(METHOD)
@Retention(RUNTIME)
public @interface AroundInvoke {
}

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";
  }
}

@DenyAll

@DenyAll annotation marks a method as forbidden to all users.

@Target({METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface DenyAll {
}

@Interceptor

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

@Target({TYPE})
@Retention(RUNTIME)
public @interface Interceptor {
}

@InterceptorBindingType

@InterceptorBindingType is a WebBeans meta-annotation for creating interceptor binding types. Applications will use @InterceptorBindingType 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.

@Target({TYPE})
@Retention(RUNTIME)
public @interface InterceptorBindingType {
}

@Interceptors

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

@Target({TYPE,METHOD})
@Retention(RUNTIME)
public @interface Interceptors {
  public Class []value();
}

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;
  }
}

InvocationContext

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

public interface InvocationContext {
  public Object proceed() throws Exception;

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

@PermitAll

@PermitAll annotation marks a method as allowed for all users.

@Target({METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface PermitAll {
}

@RolesAllowed

@RolesAllowed 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.

@Target({TYPE,METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface RolesAllowed {
  String []value();
}

@RunAs

@RunAs changes the security context user to a defined role. Security tests within the context of the @RunAs will match the specified role.

@Target({TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface RunAs {
  String value();
}

@TransactionAttribute

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

All Resin-managed beans can use @TransactionAttribute: @Stateful, @Stateless, @MessageDriven and plain Java beans.

• SUPPORTS is typically used for read-only methods
• REQUIRED is typically used for updating (read/write) methods

@Target({TYPE,METHOD})
@Retention(RUNTIME)
public @interface TransactionAttribute {
  TransactionAttributeType value() default REQUIRED;
}

Dependency Injection Annotations

@EJB

Configures an EJB values for a field or method.

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

@Target({TYPE, METHOD, FIELD, PARAMETER})
@Retention(RUNTIME)
public @interface EJB {
  String name() default "";
  String businessInterface() default "";
  String jndiName() default "";
}

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

@EJB
void setFoo(example.Test test)
{
  _test = test;
}

@Resource

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

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

@Target({TYPE, METHOD, FIELD, PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
public @interface Resource {
  AuthenticationType authenticationType() CONTAINER;
  String description() default "";
  String mappedName() default "";
  String name() default "";
  boolean shareable() default true;
  Class<?> type() default Object.class;
}

In the following exaple, Resin will call setDataSource method with the data source in "java:comp/env/jdbc/test" before the session is started. The "java:comp/env/jdbc" full name is inferred from the DataSource type.

@Resource(name="test")
void setDataSource(javax.sql.DataSource dataSource)
{
  _dataSource = dataSource;
}