Kyle Marvin

Developer

Apache Beehive Incubator Project

Introduction to Beehive

Controls

Copyright 2004 BEA Systems. Licensed under the Apache License, Version 2.0

Agenda

Big Picture Problem and Solution

Basic Controls Architecture

Authoring a Control

Using a Real World Example

Enqueueing JMS messages

The Presentation Litmus Test:

Code-to-Text Ratio

9 slides contain mostly text

18 slides contain code or architecture diagrams

I hope I got the ratios right, and you find this interestingand informative!

Big Picture Problem

Enterprise Resource Access has too many APIs!

JDBC, EJB, JMS, JAX-RPC, JCA, …

Many emerging ease-of-use models are still resource-specific

(ex. EJB3).

Results in two key problems:

Problem #1: developer learning curve

Problem #2: tool support

Solution: Beehive Controls

Provides a single consistent model no matter what the resource!

And that model is JavaBeans!

Declarative authoring model

Additional runtime services

Tool integration

Property introspection and presentation

Declarative programming

JAR packaging model for discovery and distribution

Focus developers on “what”, not “how”

Make mechanisms/plumbing less visible!

Simple things should be simple!

But … complex things should be possible!

Beehive Controls == JavaBeans

Controls conform 100% to JavaBeans spec

Bean Properties = Resource Configuration Options

Bean Methods = Resource Operations

Bean Events = Resource Notifications

A well-defined model for discovery/tooling

Bean introspection

Jar packaging

A well-defined model for usage

Use a Control anywhere a JavaBean can be used

Ex. <jsp:useBean>

Basic Controls

Runtime Architecture

Resource

Client

Resource

Control

Bean

JSR-175 Metadata

and/or

External Configuration

Events

Properties

Resource

Actions/Data

Resource

Proxy

Operations

Property

Accessors

Controls are JavaBeans++

Authoring:

Declarative model for bean authoring

Separation into public interface and implementation

Extensibility model for creating resource views

Runtime:

Management of property state, event listeners

Contextual services

Resource lifecycle notifications

Richer configuration model

Control Authoring Model:

Control Public Interface

@ControlInterface

public interface JmsMessageControl

{

Properties

Events

Operations

Extensibility Model

}

Control Authoring Model:

Control Implementation Class

@ControlImplementation

public class JmsMessageControlImpl

implements JmsMessageControl

{

Operations implementation

Event notifiers

Contextual services

Nested Controls (composition)

Extensibility model implementation

}

Control Authoring Model:

ControlBean Generated Class

Code-generated from Public Interface

public class JmsMessageControlBean

implements JmsMessageControl

extends ControlBean

{

Property setters/getters

Event listener management

Contains impl instance (delegate)

Configuration services

}

ControlBean Runtime Architecture

ControlBean

Generated

Class

Control

Implementation

Class

Control

Public

Interface

Operations

Events

Property

Values

Actions/Data

Property Accessors

Event Registration

Property

Values

C

L

I

E

N

T

R

E

S

O

U

R

C

E

JSR 175 Metadata and/or

External Configuration

Resource

Proxy

Declaring Control Properties:

Control Public Interface

@ControlInterface

public interface JmsMessageControl

{

…

public enum DestinationType { QUEUE, TOPIC }

@PropertySet(prefix=”Destination”)

@Target({FIELD, TYPE})

public @interface MessageDestination

{

public DestinationType type() default QUEUE;

public String jndiName();

}

Properties are declared using JSR-175 annotation types

Provides:

Declarative syntax for setting properties

Interface for exposing property values to implementation

JavaBean Property Accessors:

ControlBean Generated Class

public class JmsMessageControlBean

implements JmsMessageControl

extends ControlBean

{

…

public void setDestinationType(DestinationType type) { … };

public DestinationType getDestinationType() { … };

public void setDestinationJndiName(String jndiName) { … };

public String getDestinationJndiName() { … };

…

}

Property setters/getters are auto-generated from the PropertySetdeclaration

Property values maintained and managed transparently

Flexible Property Model:

How Properties Can Be Set

Using JavaBean setters:

myJmsControlBean.setDestinationType(QUEUE);

myJmsControlBean.setDestinationName(“jndi:/queues/InvoiceQueue”);

Using JSR-175 annotations:

@Control

@MessageDestination(type=QUEUE, name=“jndi:/queues/InvoiceQueue”)

public JmsMessageControlBean myJmsControlBean;

Using externalized configuration data:

<bean class=“org.apache.beehive.controls.samples.JmsMessageControl”>

<property name=“MessageDestination.Type” value=“QUEUE” />

<property name=“MessageDestination.Name” value=“jndi:/queues/InvoiceQueue” />

</bean>

Flexible Property Model (cont)

Question: Which way is best?

Answer #1: It depends.

No one mechanism is sufficient

Annotations are rigid (requires recompile)

External configuration obsfucates intent

Only providing APIs is tool-unfriendly

Answer #2: Freedom of choice is what really matters

Well-defined precedence resolution model:

Lowest: JSR-175 Annotations

Medium: External Configuration

Highest: Client-set values

PropertySets can the available mechanisms

Accessing Property Values:

Control Implementation Class

@ControlImplementation

public class JmsMessageControlImpl

implements JmsMessageControl

{

@Context

ControlBeanContext beanContext;

…

MessageDestination msgDest =

beanContext.getControlPropertySet(MessageDestination.class);

Property Access provided by ControlBeanContextcontextual service

Declaring Events

Control Public Interface

@ControlInterface

public interface JmsMessageControl

{

…

@EventSet

public interface MessageEvents

{

public void onMessageSent(Message msg);

}

Declared as inner interfaces of Public Interface

Annotated by @EventSet

Event Listener Registration:

ControlBean Generated Class:

public class JmsMessageControlBean

implements JmsMessageControl

extends ControlBean

{

…

public void addMessageEventsListener(MessageNotification ml)

{ … }

public void removeMessageEventsListener(MessageNotification ml)

{ … }

…

}

Event listener registration/deregistration APIs are auto-generated from theEventSet declaration

Listener list(s) are transparently managed

Raising Events:

Control Implementation Class

@ControlImplementation

public class JmsMessageControlImpl

implements JmsMessageControl

{

@Client

MessageEvents messageClient;

…

msgClient.onMessageSent(msg);

…

};

@Client annotation identifies event notifier proxies

Initialized by the containing ControlBean

Used to send notifications to all registered listeners

Control Operations

Control Public Interface

@ControlInterface

public interface JmsMessageControl

{

…

public void sendTextMessage(String text);

public void sendObjectMessage(Object o);

…

}

All methods declared directly on the Public Interface are operations

The ControlBean implements the Public Interface and delegates operationinvocations to…

The Control Implementation Class implements all operations on thepublic interface.

Contextual Services

Provide runtime services and events to Controls

Can be requested declaratively or programmatically byControl Implementation classes:

@Context

ControlBeanContext beanContext;

Based upon J2SE JavaBeans Extensible RuntimeContainment and Services Protocol(http://java.sun.com/products/javabeans/glasgow/#containment)

Supplied at runtime dynamically based upon executioncontext of Controls

Contextual Services:

Some Examples

@Context ControlBeanContext

Provides access to properties

Provides basic lifecycle events (onCreate, …)

Programmatic access to other services

@Context ResourceContext

Provides resource mgmt lifecycle events

onAcquire: acquire supporting resources, such as connections,sessions, …

onRelease: release supporting resources

Synchronized to external container request or transaction lifetimes

Container-specific contextual services:

@Context ServletContext (web tier)

@Context EJBContext (EJB tier)

Extensibility by Interface

Extension by Interface enables the creation of a customized set ofoperations or events for a specific resource use case

The JMS Message Control defines a generic resource access model forenqueueing messages to any destination

A ControlExtension of the JMS Message Control might define a specificsets of messages targetting a specific queue.

Each method (or event) on the Extension Interface defines a new resource

action (or event) with a specific bound

Extension semantics are defined by the Control Public Interface

Appear as annotation types that can be used on TYPE, METHOD, or

PARAMETER

In the following example, the JMS Message Control enables thedefinition of methods that will enqueue messages with a specificformat

Extensibility by Interface:

Defining Extension Semantics

@ControlInterface

public interface JmsMessageControl

{

public enum MessageType { BYTES, MAP, OBJECT, STREAM, TEXT }

@Target({METHOD}) @Retention(RUNTIME)

public @interface Message

{

public MessageType value() default TEXT;

}

@Target({PARAMETER} @Retention(RUNTIME)

public interface Body {}

@Target({PARAMETER}) @Retention(RUNTIME)

public @interface Property

{

public String name();

}

}

Extensibility By Interface:

Defining a ControlExtension

@ControlExtension

@Destination(type=QUEUE, jndiName=”jndi:/queues/orders”)

public interface OrderQueue extends JmsMessageControl

{

public class Order implements java.io.Serializable

{

public Order(int buyer, String list) { buyerID = buyer; itemList list; }

int buyerID;

String [ ] itemList;

}

@Message (OBJECT)

public void submitOrder(

@Body Order order,

@Property ( name=“DeliverBy”) String deliverBy);

Extensibility by Interface:

Implementing the Extension

@ControlImplementation

public class JmsMessageControlImpl

implements JmsMessageControl, Extensible

Object invoke(Method m, Object [] args) throws Throwable

{

…

// Identify the parameter that contains the message body

int bodyIndex = 1;

for (int i= 0; i< args.length; i++)

if (context.getArgumentPropertySet(m, i, JMMessageControl.Body.class) != null)

bodyIndex = i;

// Get the message type

JMSMessageControl.Message msgProp =

context.getMethodPropertySet(m, JMSMessageControl.Message.class);

Packaging Model

Controls can be packaged in JAR files for distribution

Contain JavaBean MANIFEST.MF entries

Annotations that enable declarative definition of manifestentries or BeanInfo introspection descriptors:

@ManifestAttribute(s) -> JAR manifest entries

@FeatureInfo -> java.beans.FeatureDescriptor

@BeanInfo -> java.beans.BeanDescriptor

@PropertyInfo -> java.beans.PropertyDescriptor

…

Will codegen custom BeanInfo classes

Can externalize strings as resources for localization

Finding out more

Go to the Apache Beehive Project site:

http://incubator.apache.org/beehive/

Control documentation:

http://incubator.apache.org/beehive/Controls.html

Controls Tutorial:

http://incubator.apache.org/beehive/controls/tutorial_controls.h

tml

Controls API reference:

http://incubator.apache.org/beehive/reference/classref_controls

/index.html