Developing services

As described in the Service Tutorial section, developing services with Rio is straight forward. For this section we will focus on service development using POJOs. This section will review the following topics:

• Service Lifecycle
• Proxy Creation
• Properties and Configuration

For information on how to perform the discovery of other services, and how to wire up your distributed application, refer to the section that discusses [Associations].

Service Lifecycle

When a service is instantiated it goes through various states.  The following state diagram shows the state transition an instantiated service goes through.

Rio will invoke lifecycle methods on your bean if the bean has the following methods defined:

public void preInitialize();
public void postInitialize();
public void preStart();
public void postStart();
public void preAdvertise();
public void postAdvertise();
public void preDestroy();

Alternatively, you can use the @Initialized and @Started lifecycle annotations:

@org.rioproject.bean.Initialized
public void myInitMethod() {
    // do something after you have been initialized
}

@org.rioproject.bean.Started
public void afterStartedMethod() {
    // do something after you have been started
}

Using these lifecycle notification methods, you may trigger certain actions. For example, if you would like to start activity when your service has been publicly advertised, you would declare the postAdvertise() method.

If you have any associations that are declared to be of type 'requires', you will not be advertised until those association(s) have been resolved. Conversely, if any of those required associations become broken, your service will be unadvertised.

Proxy Creation

The bean may also define a smart proxy. In order for the service infrastructure to obtain the smart proxy the following method signatures must be defined:

public Object createProxy();

Using the createProxy method, the method passes a remote reference to the exported back end implementation. This parameter can be declared to be the interface type your proxy implements, or a Object, which can then be narrowed to the interface type the bean implements. The method must return the bean's smart proxy, using the reference provided.

public void setProxy(Object);

If the bean has the setProxy method declared, this method will be invoked with the proxy that has been created for the bean.

Alternatively, the bean can use the CreateProxy and SetProxy annotations:

@org.rioproject.bean.CreateProxy
public Object createMyProxy(Foo foo) {
    // create and return your custom proxy
}

The argument passed to your annotated method is the remote reference of the exported service. You need this to create your smart proxy, since your proxy will be delegating remote calls to this reference.

If you need to have the proxy that is created by the service infrastructure injected to your service, you can alternatively use the SetProxy annotation:

@org.rioproject.bean.SetProxy
public void setMyProxy(Foo fooProxy) {
    this.fooProxy = fooProxy;
}

Both the CreateProxy and SetProxy annotations take precedence over the respective declared methods enumerated above.

Properties and Context

Properties, the Configuration, the ServiceBeanContext and the service bean itself can be injected into the bean as well. The following methods must be declared to have the respective properties injected into the bean:

public void setParameters(Map parameters);
public void setConfiguration(Configuration config);
public void setServiceBeanContext(ServiceBeanContext context);
public void setServiceBean(ServiceBean serviceBean);

Property/configuration injection is completed during the initialization of the ServiceBean (initialization is a sub-state of started).