Objective

The objective of this paper is to provide answers to a number of common questions about the architecture that supports Controls in version 8.1 of WebLogic Workshop. Those questions include:

• Are Controls EJBs? If so, what kind. If not, what are they and why aren't they EJBs.
• What does the runtime architecture for Controls look like (i.e. what are the major components and what are their responsibilities)?
• What happens during compile/build? What things get built and where to they go?

Intended Audience

This paper is targeted toward J2EE practitioners that want to understand more about how Controls are mapped onto the J2EE runtime (i.e. what happens "behind the scenes").

New Features in Workshop 8.1

Version 7.0 of Workshop introduced Controls as a means to simplify the programming model for accessing enterprise resources. A more complete description of the motivation for Controls and the programming model can be found in these white papers. While the Controls architecture in version 7.0 provided support for extending Controls (i.e. CTRL files), users could not create their own Controls. Version 8.1 of Workshop provides users and ISVs the ability to build their own Controls. The development model for Controls is very similar to that of building a JWS or JPD (i.e. a design view with operations, callbacks, and properties). More advanced developers can use a declarative XML syntax to describe annotations for their Controls and can build IDE plug-ins for validation and insert wizards. There is a Control Developers Kit (CDK) provided as part of the Workshop installation (<install>\weblogic81\samples\workshop\ControlDevKit).

Questions and Answers

Are Controls EJB?
No, Controls are not EJBs. Controls (like Web Services and Workflows) are just Plain Old Java (POJ) classes that include metadata that is used to configure and control runtime behavior. When a project is built, there are always resulting .class files that correspond to the user's source files. Those .class files include the metadata that was included in the original source file. At runtime, the infrastructure uses EJBs along with the stored metadata to control invocation of user code. This insures that Controls always run in the context of an EJB without having to be an EJB.

A primary reason for this approach is to leverage the runtime support provided by EJBs without having the large deployment footprint that would result from having every user artifact become a deployed EJB.

What Does the Runtime Architecture for Controls Look Like?
Architectural components within the runtime are organized around two key runtime responsibilities:

• Dispatch - Given a request, find the appropriate user code to execute.
• Invocation - Invoke the user code with the correct runtime context.

The following diagram provides an overview of the components within the runtime architecture. The diagram also highlights the concepts of top-level and nested context. This is how Controls that appear to be invoked from the web tier (i.e. from a JSP or JPS) are actually invoked in the EJB tier via the WlwProxy.



Dispatch
Dispatch requires that a request be routed to the appropriate method on a user written component (e.g. .JWS, JPD, JCS). In the case of a JWS or JPD, this includes determining if the request is starting, continuing or finishing a conversation. In all cases, it also includes determining whether a request is an operation or an asynchronous callback.

Note that while controls can be stateful, they are not conversational. If the outermost component (JWS or JPD) is conversational, then any nested controls will participate in the conversation of the outermost component.

For a Web Service or JPD, the point of entry for dispatch functions is either a HTTP Servlet or a JMS transport Message Driven EJB. For a JPF, an infrastructure proxy is used to redirect operations on controls to a Container EJB.

In all cases, the server side dispatch is handled by an infrastructure EJB. The specific EJB that handles a request is determined based on the type of request and whether the request represents a delivery failure.

• com.bea.wlw.runtime.core.bean.SyncDispatcherBean - a Stateless Session EJB that provides synchronous dispatch of requests to user code.
• com.bea.wlw.runtime.core.bean.AsyncDispatcherBean - a Message Driven EJB that provides asynchronous dispatch of requests to user code.
• com.bea.wlw.runtime.core.bean.AsyncErrorBean - a Message Driven EJB that provides notification of asynchronous delivery failures. This MDB is responsible for delivering the onAsyncFailure context event.

The Dispatch EJB resolves the request to a Container EJB that will provide the context for top-level and subsequent nested invocation. There is a generic "shared" Container EJB that can host Controls and Stateless JWS/JPD operations - as long as there are no annotations that specify special runtime characteristics (e.g. security annotations). There are a number of cases, where a user component will have it's own Container EJB generated along with an Adapter.

• JWS/JPD with conversational methods.
• Any component (including Controls) with security annotations or buffered operations.

Note that the name Container EJB should not be confused with Container Managed Persistence (CMP). Container EJBs are Workshop shared or generated EJBs that are used to provide the execution context for user code.

Invocation
Once the dispatch logic has located the correct user component (and instance if appropriate), the next step is to invoke the user's code with the parameters in the request. Control invocation is accomplished through:

• A Dynamic Proxy
• A Control Container
• The "Invocable" Abstraction

Keep in mind that the user of a Control is only aware of the Control's interface (e.g. the public interface of a JCS or a JCX).



The Control Container provides lightweight initialization, event, and dispatch services for Controls. Each type of user code within Workshop has an associated runtime container (e.g. JWS, JPD, Controls).

The "Invocable" abstraction provides a consistent means for representing an executable method/operation as well as the mechanism for using reflection to invoke user code.

Note that this pattern can be nested. Now that a Control can have references to other Controls, it's possible to have a Control nested within another Control. At runtime, the invocation always starts with an operation on a Container EJB (generic or generated) and continues to execute until the bottom of the nesting or until a buffered operation is encountered

What Gets Built and Where Does It Go?

What Gets Built
There are two basic activities that take place during the build of a Workshop project.

• Compiling user source files
• Generating Container EJBs

Compiling user source files is only interesting because the resulting class files include metadata based on annotations found in the source. Currently those annotations are expressed as javadoc comments. This is an interim approach until JSR-175 is finalized and available as part of the JDK/JRE.

Generating Container EJBs and Adapters takes place when a specific (rather than generic) Container EJB is required to support invocation of user code (e.g. there are declarative security annotations). In this case, the generated Container EJB has methods that match the operations defined on the users code, and a single method for nested controls that receive external callbacks. The generated Adapter allows EJBs with application specific APIs to be used in the generic invocation architecture.

Where Does It Go
All generated code is placed under the .workshop directory under the application's root directory. Workshop applications make use of the split-source model for code management. The following diagram illustrates the directory structure for workshop applications.

• Compiled web-tier components (e.g. JPFs and control interfaces) are placed under the "output" directory in a subdirectory matching the name of the web-application. This makes the control interfaces visible to the web tier even through the control implementation runs in the EJB tier.
• Compiled ejb-tier components (e.g. JWS, JPD, JCS) are placed under the "classes" directory in a subdirectory matching the name of the web-application. This is the compiled user code (along with annotations) that will be executed by Container EJBs at runtime.
• All EJBs are placed in a directory named EJB in a subdirectory matching the name of the web-application. Dispatch related EJB are located under the "ProjectBeans" directory. Component specific Container EJBs are located under a directory that whose name is derived from the component's name suffixed with the mangled package name. The mangling of package names is done to try and minimize the length of generated file paths/names. Each project contains a "default" Container EJB named "GenericStateless". This "shared" Container EJB can be used to host invocation of any user component that does not have specific invocation requirement (i.e. do not have an generated Container EJB and Adapter).

Conclusion

This paper has attempted to provide answers to a number of common architectural questions about Controls. In summary:

• Controls are not EJBs, however they leverage infrastructure that insures that a Control always executes in the context of a Container EJB, even if the Control is invoked from within a JPF or JSP.
• The runtime architecture is organized into a set of EJBs that are responsible for dispatch functions and another set of EJBs that provide runtime context for invoking user code (i.e. Container EJBs). Invocation of Controls is handled by a lightweight Control Container and is accomplished by loading the runtime components via a Dynamic Proxy.
• Workshop utilizes the split-source model of development. This allows generated and compiled artifacts to exist in a separate, but parallel directory structure. This parallel output directory structure is in the .workshop directory directly under the root of the application.