Package org.beanlet

Contains all of the core beanlet interfaces and bootstrap classes.

See:
Description

Interface Summary

BeanletContext<T>	Provides beanlet instances access to their runtime context.
BeanletFactory<T>	Factory for creating beanlet references.
BeanletMetaData<T>	Provides information on the beanlet definition.
BeanletReference<T>	Represents a reference to a beanlet.
Event	Root interface of all events.
FactoryBeanlet<T>	Beanlets implementing this interface can act as a factory.
Interceptor	Classes implementing this interface can configured to intercept invocations.
InvocationContext	Allow interceptor and lifecycle methods to control the behavior of the invocation chain.
MetaData	Root interface of all meta data objects.

Class Summary

BeanletApplicationContext

Bootstrap class for the application container.

Enum Summary

AttributeAccessType	Specifies the access rights for attributes.
RetentionPolicy	Beanlet retention policy.
WiringMode	Specifies the wiring mode.

Exception Summary

BeanletApplicationException	Thrown to indicate a general application error.
BeanletCreationException	Thrown if an instance for the specified beanlet could not be created, or obtained for some reason.
BeanletDefinitionException	Indicates an invalid beanlet definition.
BeanletEventException	Generic event exception.
BeanletEventNotExecutableException	Thrown if specified event cannot be executed.
BeanletException	Indicates that there is an issue with the specified beanlet.
BeanletExecutionException	Exception thrown if any exception is raised during event execution.
BeanletNotActiveException	Thrown if the specified beanlet has not yet been activated.
BeanletNotFoundException	Thrown if no beanlet is registered for the specified name.
BeanletNotOfRequiredTypeException	Thrown if required type does not matched found type.
BeanletStateException	Indicates that beanlet is not in required state to perform operation.
BeanletTypeIsDuplicateException	Indicates that multiple beanlets match the member type.
BeanletTypeMismatchException	Thrown if injectant does not match member type.
BeanletTypeNotFoundException	Exception thrown if no beanlet type matches member type.
BeanletValidationException	Thrown if beanlet validation failed.
BeanletWiringException	Thrown if any of the members, for which injection is required, cannot be wired.

Annotation Types Summary

AroundInvoke	Designates a method to intercept invocations on a beanlet.
Attribute	Exposes methods or fields as beanlet attributes.
CollectionValue	Represents a collection of values.
Dependency	Used to specify an explicit dependency.
Entry	Represents a single map entry.
ExcludeClassInterceptors	Used to exclude class-level interceptors for a business method.
ExcludeDefaultInterceptors	Used to exclude default interceptors for a class or method.
Execute	Methods declared with this annotation are executed by one or more background threads.
Factory	Beanlets implementing this annotation can act as a factory.
IgnoreDependency	Used to ignore the dependencies of the element that is subject to injection.
Inject	Members marked with this annotation are injected by the application container during beanlet instance creation.
Interceptors	Declares a list of interceptors.
Lazy	Beanlets marked with this annotations are not eagerly instantiated.
MapValue	Represents a map of key/value entries.
Operation	Exposes methods as beanlet operations.
PostConstruct	The PostConstruct annotation is used on a method that needs to be executed after dependency injection is done to perform any initialization.
PreDestroy	The PreDestroy annotation is used on methods as a callback notification to signal that the beanlet instance is in the process of being removed by the container.
Proxy	Specifies interfaces to be exposed by beanlet.
ProxyMethod	Methods marked with this annotation are so-called proxy methods.
Remove	Applied to a business method of a class.
Retention	Indicates what action is to be taken in case an exception is encountered on beanlet invocation.
Schedule	Methods declared with this annotation are scheduled to be executed by a background thread.
ScopeAnnotation	Annotations marked with the ScopeAnnotation are beanlet scope annotations.
Start	The Start annotation is used on a method that needs to be called after initialization of a beanlet.
Stateful	Stateful beanlet maintain conversational state between calls on the same object.
Stateless	Stateless beanlets do not share any state between subsequent method invocations.
Stop	Defines a stop lifecycle method.
Value	Defines an object.
Vanilla	Vanilla beanlets are the most straight forward type of beanlets within this specification.
Wiring	Allows members to be wired with implicitely selected objects.

Package org.beanlet Description

Contains all of the core beanlet interfaces and bootstrap classes.

Beanlet Scopes

The Beanlet core packages come with three object scopes:

• Vanilla beanlets are the most straight forward type of beanlets within this specification. Unlike the scopes described below, vanilla beanlets do not have a stub that controls access to the beanlet instance. Clients have access to the actual object. In short, they can invoke methods directly on the beanlet instance.
  A new beanlet instance is created for each beanlet that is explicitely requested throuh the APIs, or implicitly through dependency injection.
  Vanilla scoped beanlets can also be configured to be singleton. In this case, the container guarantees that only a single instance of this beanlet exists at the same time. It is always this particular instance that is returned when this beanlet is requested.
• Stateful beanlets do not provide direct access to the underlying objects. Instead, clients obtain a stub, which delegates invocations to the underlying instance. In case of stateful beanlets, invocations are always delegated to the same instance.
  A new beanlet instance is created for each beanlet that is explicitely requested throuh the APIs, or implicitly through dependency injection.
  Stateful beanlets are non reentrant by default, which means that only one thread can invoke a method of the beanlet instance at the same time. This feature is provided by the stub, which controls all access to the underlying instance. Stateful beanlets can also be configured to be reentrant.
• Stateless beanlets are the counterpart of stateful beanlets. Stateless beanlet instances are pooled. Methods called on stateless beanlet stubs are delegated to one of a pool of instances. If multiple invocations are made on the same stub reference, different beanlet instances can be used to perform the call.
  Beanlet instances are added and removed from the pool at container's discretion. Requesting a beanlet stub through the APIs, or dependency injection does not necessarily result in the creation of a new beanlet instance. In general, the number of pooled beanlet instances depends on the number of concurrent requests made to these stubs.
  Stateless beanlets can be configured to be reentrant and singleton.

Static versus Non-Static

Beanlets are created in either a static or a non-static context. Static, in this context, means that beanlets are created independently from the current state of the container or application. Static beanlets are created at the container's discretion and therefore do not allow applications to pass any state to this component while it is being created. Non-static beanlets are only created upon application request. Applications can pass objects - or state if you will - by using wiring BY_INFO dependency injection. Use the BeanletMetaData interface to find out if a beanlet is static programmatically.

The static property of a beanlet is derived from the selected beanlet scope, i.e., singleton vanilla beanlets are static, where non-singleton vanilla beanlets are non-static. The following table shows the static property for all core beanlet scopes.

	singleton	reentrant	static
Vanilla	true	N/A	true
Vanilla	false	N/A	false
Stateful	true/false	true/false	false
Stateless	true/false	true/false	true

The static property has also effect on the lifecycle management of beanlets as is explained by the next paragraph.

Beanlet Lifecycle Management

The container is responsible for managaging the lifecycle of beanlets. Two lifecycle levels can be identified. That is, at instance-level and at business-level.

Instance-Level

Instance-level lifecycle methods are invoked during the process of creating or destroying individual beanlet instances. These lifecycle methods are marked with the PostConstruct and PreDestroy annotations, respectively. These methods are invoked in an unspecified context. This means that transactions, for instance, are not supported for these methods.
The PostConstruct method is invoked right after dependency injection. This method has to be completed before any business methods can be invoked on the instance. The PreDestroy method is the last method to be invoked on the beanlet instance. Whether the PreDestroy method is actually invoked depends on the RetentionPolicy specified by the beanlet.

Business-Level

Business-level lifecycle methods are in genereral no different from any other business methods, except that they are invoked by the container directly. These lifecycle methods are marked with the Start and Stop annotations, respectively.
For non-static beanlets, business-level lifeycle methods are processed at beanlet instance level. This is quite similar to the instance-level lifecycle methods described above, except that the business-level lifecycle methods do run in a specified context (and thus support transactions). As a result, the Start and Stop methods of a non-static beanlet can be invoked multiple times, namely once per constructed instance.
For static beanlets, business-level lifecycle methods are processed at beanlet level. If a beanlet specifies a Start method, the container requests a beanlet instance during deployment and invokes this Start method. The Stop method is invoked if the beanlet is being undeployed. In other words, the Start and Stop for static beanlets are invoked only once.

Beanlet Definitions

Throughout this API, the following definitions are used:

• Beanlet is, in general, the name used to identify the objects clients interact with. In other words, the name 'beanlet' is used for the objects that are injected, and objects that are returned by the APIs ( BeanletApplicationContext and BeanletReference). The 'beanlet' might actually be a 'beanlet instance' in case of vanilla beanlets, or a 'beanlet stub' for stateful or stateless beanlets.
• Beanlet instance is the underlying object of a beanlet. Beanlet instances provide the actual business logic of the beanlet. The lifecycle of beanlet instances is fully controlled by the container.
• Beanlet stub acts as a proxy and controls access to the underlying beanlet instances.
• Beanlet definition stands for the component declared at the beanlet xml-files. More specificly, a beanlet is defined by the <beanlet> xml-tag. A 'beanlet definition' embodies all properties that constitute a beanlet, like its name, type, classloader and meta data. The 'beanlet defintion' can be accessed programatically through the BeanletMetaData interface.
• Beanlet type is the type as expressed by the <beanlet> xml-tag. The beanlet type is not necessarily the same as the type of the beanlet instance. The beanlet instance may be a subclass of the expressed beanlet type. More specifically, the type of the beanlet instance can vary for each individual instance. Therefore all properties of the beanlet are derived from the beanlet type, which is static. The beanlet type can be obtained via BeanletMetaData.