BEA WebLogic is a J2EE application server and also an HTTP web server by BEA Systems of San Jose, California, for Unix, Linux, Microsoft Windows, and other platforms. WebLogic supports Oracle, DB2, Microsoft SQL Server, and other JDBC-compliant databases.

WebLogic Server supports WS-Security and is compliant with J2EE 1.3.

BEA WebLogic Server is part of the BEA WebLogic Platform™. The other parts of WebLogic Platform are:Portal, which includes Commerce Server and Personalization Server (which is built on a BEA-produced Rete rules engine),

WebLogic Integration,

WebLogic Workshop, an IDE for Java, and

JRockit, a JVM for Intel CPUs.

WebLogic Server includes .NET interoperability and supports the following native integration capabilities:

Native enterprise-grade JMS messaging

J2EE Connector Architecture

WebLogic/Tuxedo Connector

COM+ Connectivity

CORBA connectivity

IBM WebSphere MQ connectivity

BEA WebLogic Server Process Edition also includes Business Process Management and Data Mapping functionality.

WebLogic supports security policies managed by Security Administrators. The BEA WebLogic Server Security Model includes:

Separate application business logic from security code

Complete scope of security coverage for all J2EE and non-J2EE components

WebLogic History

WebLogic, Inc., was founded by Paul Ambrose, Bob Pasker, Laurie Pitman, and Carl Resnikoff, in September, 1995. Up until then, Paul and Carl had been developing (pre-JDBC) Oracle, Sybase, and Microsoft SQL Server database drivers for Java under the name dbKona, as well as a "three tier" server to permit applets to connect to these databases. An old dbKona/An T3 Usenet posting. This was the WebLogic 1.48 server, and was called T3Server (a bastardization of 3-Tier Server).

Concurrently, Laurie and Bob had been working on network management tools in Java. Bob had written a SNMP stack in Java and a W32 native method for ICMP ping, while Laurie worked on applets to display the management data.

One of the hidden features of the 1.48 server version was the ability to extend it by modifying a dispatcher and adding a handler for different types of messages. Bob talked Paul into sending him the source code for the server, and Bob extended it so that Applets could make SNMP and PING requests on the network, and display the results.At this point, the founders worked together to pursue what was eventually to be called the Application Server.

The WebLogic Workshop Development Environment

WebLogic Workshop is an integrated development environment for building enterprise-class J2EE applications on the WebLogic Platform. WebLogic Workshop provides an intuitive programming model that enables you to focus on building the business logic of your application rather than on complex implementation details. Whether you are an application developer with a business problem to solve or a J2EE expert building business infrastructure, WebLogic Workshop makes it easy to design, test, and deploy enterprise-class applications.

WebLogic Workshop consists of two parts: an Integrated Development Environment (IDE) and a standards-based runtime environment. The purpose of the IDE is to remove the complexity in building applications for the entire WebLogic platform. Applications you build in the IDE are constructed from high-level components rather than low-level API calls. Best practices and productivity are built into both the IDE and runtime.

WebLogic Workshop is available in two editions:

WebLogic Workshop Application Developer Edition includes the basic features required by application developers to build web services, web applications, custom controls and Enterprise JavaBeans (EJBs). All editions of WebLogic Workshop also include ubiquitous support for XMLBeans, BEA's technology for seamless, natural manipulation of XML in Java. WebLogic Workshop Platform Edition includes additional extensions to the IDE and runtime framework that let you build portal applications and business processes in conjunction with the WebLogic Portal and WebLogic Integration products, respectively. WebLogic Workshop's intuitive user interface lets you design your application visually. Controls make it simple to encapsulate business logic and connect to enterprise resources, like databases and Enterprise JavaBeans, without writing a lot of code. Conversations handle the job of keeping track of application state. And WebLogic Workshop's support for asynchronous processes makes it easy to build highly reliable applications for the enterprise.

Developing Applications with WebLogic Workshop

The topics in this section address the basic concepts you need to understand to build entrprise-class applications with WebLogic Workshop.

What Can I Build with WebLogic Workshop?

The WebLogic Workshop IDE builds enterprise-class applications that run in the WebLogic Workshop runtime. The applications you build in WebLogic Workshop typically expose systems and data within or between enterprises, typically via web applications and/or web services. As an example, considering an express shipping company. Such a company might want to expose shipment scheduling, tracking and billing data to its business partners via web services so that partners' applications can access the data directly. The company also might want to expose tracking information via one or more web applications so that shipment originators and recipients can check the status of shipments from a web browser. WebLogic Workshop makes it easy to construct common functionality for both applications and then expose that functionality with appropriate interfaces.

In WebLogic Workshop Application Developer Edition, the core components are:

Java controls

Web services

Web applications

Enterprise Java Beans (EJBs)

In WebLogic Workshop Platform Edition you can also build:

Portal Applications

WebLogic Integration components: business processes, data transformations, integration-specific controls

What is an "Enterprise-class" Application?

"Enterprise-class" applications exhibit specific attributes. The J2EE foundation on which the WebLogic Platform and WebLogic Workshop is built provides reliability, availability and scalability as well as caching, security and transaction support. "Enterprise-class" also refers to additional specific attributes with regard to web services and web applications:

Enterprise-class web services are loosely-coupled and coarse-grained and optionally asynchronous. To learn more about how WebLogic Workshop enables these attributes, see Why Build Web Services with WebLogic Workshop?.

An enterprise-class web application exhibits a separation between its application logic and its presentation logic. WebLogic Workshop enables this separation with Java page flows, which are based on the well-established Model-View-Controller pattern. To learn more about Java page flows, see Developing Web Applications.

How WebLogic Workshop Simplifies Development

As you read about the various components of a WebLogic Workshop application in the sections that follow, there are two common threads you will notice: the use of Java classes with powerful custom

Javadoc annotations and the presence of custom design and development tools for each component type.

Javadoc Annotations

Each of the major components of a WebLogic Workshop application is expressed as a single Java class that is annotated with special Javadoc annotations (also called Javadoc annotations). The Javadoc annotations indicate to the WebLogic Workshop runtime that the component developer wants to utilize or configure particular features of the runtime.For example, the @common:operation Javadoc annotation on a method in the Java class defining a web service indicates that that method should be exposed as an operation in the web service's WSDL file. As another example, the @jpf:forward Javadoc annotation on a method in the Java class defining a Java page flow indicates the page to which the user should be directed when that action is invoked. Via these annotations, WebLogic Workshop hides the vast majority of the complexity of implementing sophisticated applications. The Javadoc annotations are typically managed for you; they are represented as "properties" in the IDE.

The fact that each component type is expressed in a single Java file is also significant. In WebLogic Workshop, you never have to manage generated stub files or deployment descriptors. The WebLogic Workshop runtime analyzes the annotations and performs all of the required infrastructure plumbing automatically. As a developer, you can focus completely on the business logic of your application.While each of the core components of a WebLogic Application is expressed as a 100% pure Java class, WebLogic Workshop uses different filename extensions to denote the component types. For example, a web service is stored in a file with the .jws extension indicating Java Web Service.To learn more about the filename extensions you will encounter while working with WebLogic Workshop, see WebLogic Workshop File Types.

Component-Specific Development Tools

WebLogic Workshop provides customized editors for all of the component types. Most component types have a dedicated Design View, which provides an intuitive graphical view of the component under development and the other components with which it interacts. WebLogic Workshop also provides customized Source Editors with all of the features developers expect in an IDE including source code completion, syntax coloring and error and warning indications in real-time. In the cases where multiple languages appear in the same source file (for example, when fragments of XML are used in a web service source file to specify XML <-> Java mapping), the Source Editor automatically adjusts its behavior to the language of the file segment in which the cursor is currently located.

Finally, WebLogic Workshop provides full two-way editing: any changes you make in the source view of a component are immediately reflected in the graphical view and vice versa.

Java Controls

All of the entities in the diagram that include the word "control" are Java controls. A Java control encapsulates business logic or facilitates access to an enterprise resource. Once a Java control has been

created, that control can be used easily and consistently from a web service, a page flow, a portal, a business process or another Java control.A Java control is a Java class that is annotated with special Javadoc annotations that enable features in the control when it is executed in the WebLogic Workshop runtime. A Java control may define methods and events. From the application developer's point of view, the consistent architecture of Java controls serves to greatly reduce the complexity of using the enterprise resources or business logic they encapsulate. Since all Java controls are Java classes, productivity aids such as source code-completion are available throughout the WebLogic Workshop IDE to streamline the development process.

When designing a Java control, you can see the relationship between the control, its client, and any other controls in the IDE's Design View. All of the important development activities can be accomplished by drag-and-drop or context-menu actions.

WebLogic Workshop includes several built-in controls that facilitate access to commonly used enterprise resources including databases, Enterprise Java Beans (EJBs), external web services and Java Message Service (JMS) queues and topics. You can create custom Java controls to encapsulate any business logic that is required by your application. Business or application logic might be contained in a variety of components, including EJBs or other applications. If you have the choice, however, encapsulating business or application logic in a Java control leverages the full power of the WebLogic Workshop architecture, including asynchronous execution and conversations ("conversation" is the WebLogic Workshop model for a long-running transaction).

Web Services

A Web Service is a piece of application logic that is exposed via standards such as Simple Object Access Protocol (SOAP; a specific dialect of XML)) and Web Services Description Language (WSDL). To use a web services, an application sends an XML message that requests an operation be performed. The application typically receives an XML response indicating or containing the results of the operation. WebLogic Workshop makes it very easy to create and deploy web services that adhere to web service standards, to access and process the XML messages received by web services and to format XML responses. Specifically, WebLogic Workshop provides two powerful technologies for manipulating XML in web services: XML Maps using XQuery for simple inline Java

<-> XML mapping specifications and XMLBeans for comprehensive Java <-> XML binding.

In WebLogic Workshop, a web service is a Java class that is annotated with special Javadoc annotations that provide simplified access to advanced web service features such as asynchrony, conversations, security and reliable messaging. Like all WebLogic Workshop components, Java web services can use Java controls to access business logic or enterprise resources. Everything you need to completely define a web service's operations, protocols, message formats and runtime behavior is contained in the web service's JWS file. There are no deployment descriptors to decipher and no external file generation to manage. WSDL generation for web services is completely automatic.

When designing a web service, the IDE's Design View shows you the relationship between the web service, its client, and any controls used by the web service. All of the important development activities can be accomplished by drag-and-drop or context-menu actions.While this topic is concerned mostly with components you build with WebLogic Workshop, it is important to note that WebLogic Workshop can easily inter-operate with web services built with other tools. One of the built-in Java controls WebLogic Workshop provides is the Web Service control. WebLogic Workshop can automatically generate a Web Service control from any valid WSDL file. Subsequently, the generated Web Service control can be used from any WebLogic Workshop component to access the remote web service as though it were a simple Java class.

Web Applications

To enable construction of dynamic, sophisticated web applications, WebLogic Workshop provides Java page flows. A page flow links together multiple web pages in a web application and provides a central control mechanism that coordinates the user's path through the pages and the associated flow of data. A page flow is a Java class that is annotated with special Javadoc annotations that controls the behavior of the web application Page flows use methods, and in most cases, forms and form beans (Java classes containing the data associated with a form) to manage navigation and state. A directory that contains a page flow class typically also includes one or more Java Server Pages (JSPs). The JSP files can reference custom WebLogic Workshop JSP annotations to raise actions, bind user interface components to data and access other application facilities. The actions referenced in a JSP correspond to action methods that are defined in the page flow class. These action methods implement code that can result in site navigation, data management, or invocation of business logic via Java controls. Significantly, the business logic in the page flow class is separate from the presentation code defined in the JSP files.

When designing a page flow, the IDE's Flow View shows the relationship between the pages in the web application and the actions that link the pages. All of the important development activities can be accomplished by drag-and-drop or context-menu actions. WebLogic Workshop also provides wizards to create specific types of page flows, generating the Java and JSP files that serve as a starting point for sophisticated applications. Page flows are based on the Struts architecture, which is itself based in the popular Model-View-Controller user interface design pattern. Page flows add powerful, scalable support for state management and page flows and the JSPs they manage also have complete access to Java controls to access business logic or enterprise resources.

Enterprise Java Beans

Enterprise Java Beans (EJBs) are server-side Java software components of enterprise applications. The J2EE Specification defines the types and capabilities of EJBs as well as the environment (or container) in which EJBs are deployed and executed. From a software developer’s point of view, there are two aspects to EJBs: first, the development and deployment of EJBs; and second, the use of existing EJBs from client software. WebLogic Workshop enables you to create new session, entity and message driven EJBs using a custom Design View. To learn how to create EJBs in WebLogic Workshop, see Developing Enterprise Java Beans.

WebLogic Workshop also provides a built-in control, called the EJB control, that makes it easy to use an existing, deployed EJB from your application.

Portal Applications

WebLogic Workshop Platform Edition adds the WebLogic Workshop Portal Extensions™ which allow you to build portals and portal resources using the WebLogic Workshop IDE. The portals you build are deployed using WebLogic Portal. A portal represents a Web site that provides a single point of access to applications and information and may be one of many hosted within a single WebLogic Portal server. Portals are becoming more and more important to companies who need to provide employees, partners, and customers with an integrated view of applications, information, and business processes. WebLogic Portal meets these needs, allowing companies to build portals that combine functionality and resources into a single interface while enforcing business policies, processes, and security requirements, and providing personalized views of information to end users.

From an end user perspective, a portal is a Web site with pages that are organized by tabs or some other form of navigation. Each page contains a nesting of sub-pages, or portlets—individual windows that display anything from static HTML content, dynamic JSP content or complex Web services. A page can contain multiple portlets, giving users access to different information and tools in a single place. Users can also customize their view of a portal by adding their own pages, adding the portlets they want to it, and changing the look and feel of the interface. The business problem that portals solve is illustrated in the following example. A company has the need for several types of Web presence: an Intranet for its employees, a secure site for interactions with partners, and a public Web site. WebLogic Portal’s flexible portal network architecture supports multiple implementation choices which allow re-use of resources across portals.

WebLogic Integration Components

WebLogic Workshop Platform Edition adds the capability to build WebLogic Integration components using the WebLogic Workshop IDE. WebLogic Integration enables you to design business processes that span applications, users, enterprise networks, and trading partners. WebLogic Integration's business process management (BPM) functionality enables the integration of diverse applications and human participants, as well as the coordinated exchange of information between trading partners outside of the enterprise. A business process is a graphical representation of a business process. Business processes allow you to orchestrate the execution of business logic and the exchange of business documents among back-end systems, users and trading partners (systems and users) in a loosely coupled fashion. WebLogic Workshop Platform Edition enables you to create business processes graphically, allowing you to focus on the application logic rather than on implementation details as you develop.

A business process can utilize data transformations using either a query or an eXtensible Stylesheet Language Transformation (XSLT). WebLogic Workshop Platform Edition includes a data mapper to create data transformations graphically. From the graphical representation of a data transformation, WebLogic Workshop generates a query. The generated query is invoked at runtime by the business process to

transform data. A query is expressed in the XQuery language—a language defined by the World Wide Web Consortium (W3C) that provides a vendor independent language for the query and retrieval of XML data.

WebLogic Integration also provides a standards-based integration solution for connecting applications both within and between enterprises. WebLogic Integration provides the following tools for integrating applications: application views, the Adapter Development Kit (ADK), EIS adapters and Application View Controls. By using these tools, you can integrate all your enterprise information systems (EIS). Typical IT organizations use several highly specialized applications. Without a common integration platform, integration of such applications requires extensive, highly specialized development efforts.

Applications and Projects

In WebLogic Workshop you create and build an application.

A WebLogic Workshop application is a J2EE Enterprise Application and ultimately produces a J2EE Enterprise Application Archive (EAR) file. An application may contain:

one or more projects

libraries and modules

security roles

This topic introduces applications and their contents.

Applications

An application in WebLogic Workshop is the collection of all resources and components that are deployed as a unit to an instance of WebLogic Server. It is also the top-level unit of work that you manipulate with WebLogic Workshop IDE. In the IDE, you may have at most one application open at a time. When you create a new application, you specify a name for the application. By default, new applications are created in the BEA_HOME/weblogic81/samples/workshop folder of your installation, but you should create your applications elsewhere so they cannot cause conflicts when upgrading to future versions of WebLogic Platform. An application in WebLogic Workshop contains one or more projects. Except in specific cases, such as accessing remote EJBs or web services, a WebLogic Workshop application is self-contained. Components in the projects of an application may reference each other, but they may not generally reference components in other WebLogic Workshop applications.

An application — more formally called an enterprise application — is different from a web application. Web application refers to a collection of resources, typically HTML or JSP pages, that allow users to access functionality via the Web. An application may contain zero or more web applications.

When to Create a New Application

An application should represent a related collection of business solutions. For example, if you were building an e-commerce site you might design an application that includes web applications for catalog shopping and customer account management and the components that support them (Java controls, EJBs, etc.). You might also need to deploy a human resources application for use by your employees. The human resources application is not related to the e-commerce application. Therefore, in WebLogic Workshop you would probably create two applications to separate these disparate business functions.

Applications Installed with WebLogic Workshop

WebLogic Workshop is installed with an application named SamplesApp, which contains example projects that you can explore to learn about WebLogic Workshop. The SamplesApp application is located in the file system at BEA_HOME/weblogic81/samples/workshop/SamplesApp. The following image shows the Application pane for the SamplesApp application:

WebLogic Workshop is also installed with an application named TutorialsApp that contains components used in the product tutorials. The TutorialsApp is located in the file system at BEA_HOME/weblogic81/samples/platform/TutorialsApp.

Projects

A project groups related files that comprise a component of an application.

In WebLogic Workshop Application Developer Edition, there are six default project types:

Web project

Web Service project

Control project

Control Deliverable project

EJB project

Java project

Schema project

WebLogic Workshop Platform Edition adds the following project types:

Portal project

Datasync project

Process project

WebLogic Workshop project types are defined by project templates. You may create custom project templates to meet the needs of your organization.

Web Project and Web Service Project

Web projects are typically used to expose enterprise application logic via a user interface. The user interface is constructed from Java Server Pages (JSPs), which are web pages that can interact with server resources to produce dynamic content. WebLogic Workshop defines Java Page Flows that define and contain the logic required to connect multiple JSPs. Web services are typically used to expose enterprise application logic to applications (as opposed to users). Individual web service interfaces are published via Web Services Description Language (WSDL) files. Each Web project or Web Service project ultimately produces a J2EE web application, each of which is included in the complete WebLogic Workshop application's EAR file when the application is built for deployment.

Contents of Web projects and Web Service projects are accessed via URLs. The WebLogic Workshop application is implicit in the URL for resources within that application. For example, the index.jsp sample JSP, which is located in the file system at SamplesApp/WebApp/index.jsp, is accessed from a web browser with the following URL:

http://localhost:7001/WebApp/index.jsp

Note that the name of a project becomes part of the public URL of each resource located within that project. You should choose your project names with that in mind. You can configure a Web or Web Service project to load by default if you do not want to require users to provide a project name as part of the URL. For example, users can access

http://localhost:7001/WebApp/index.jsp by simply requesting http://localhost:7001/.

To configure a project to load by default:

From the Application tab, right-click on the Web or Web Service project that you would like Web Logic Server to load by default and select Properties.

In the Project Properties dialog, select the Use project name check box..

In the text box labeled Context Path, enter / and Click OK.

The SamplesApp sample application contains a sample Web project named WebApp and a sample Web Service project named WebServices.

Note: Web projects and a Web Service projects are both J2EE web applications. Web services may be created in a web application and page flows and JSPs may be created in a web service project. The only difference between the project types is the set of supporting files the project initially contains. If you add web services to a web project or page flows or JSPs to a web service project, the necessary supporting files are automatically added to the project.

Control Project

Java controls are entities that contain business logic or provide convenient access to enterprise resources. A control project may be used to construct and package controls that are intended for use by components in other projects. For example, a custom control that provides access to a proprietary Human Resources application might be used from JSPs in a web project and also from web services in a web service project.

Each Control project ultimately produces a Java Archive (JAR) file.

The SamplesApp samples application contains a sample Control Project named ControlProject.

Control Deliverable Project

You use a control deliverable project when you want to build Java controls that will be distributed to multiple users. A control deliverable projects creates directories you can use to store help and sample files relating to the control. When you build a control deliverable project, WebLogic Workshop packages the controls of that project into a Java Archive (JAR) file along with the help and sample files that you provide in the generated help and sample directories. When users install the control, WebLogic Workshop automatically integrates the help and sample files contained in the JAR with the users existing WebLogic Workshop help installation.

EJB Project

Enterprise Java Beans (EJBs) are Java software components of enterprise applications. The J2EE Specification defines the types and capabilities of EJBs as well as the environment (or container) in which EJBs are deployed and executed. From a software developer’s point of view, there are two aspects to EJBs: first, the development and deployment of EJBs; and second, the use of existing EJBs from client software. An EJB Project provides support for creating and deploying new EJBs. Each EJB project ultimately produces a Java Archive (JAR) file and when an EJB project is built the EJBs in the project are automatically deployed to the development server.The EJB Control that is a built-in control in WebLogic Workshop allows clients such as web services, JSP pages or other controls to access existing EJBs, including EJBs created in an EJB Project.

Java Project

A Java project is a place to develop or collect general-purpose Java code that is not directly part of special entities such as web services, controls or EJBs. The product of a Java project is a JAR file that typically holds Java classes you want to access from other parts of your application. For example, a Java Project might hold Java code for a library of string formatting functions that are used in web services and JSPs in other projects in the application. By default, each Java project ultimately produces a Java Archive (JAR) file.

Schema Project

A Schema project provides convenient, automatic access to BEA Systems' XMLBeans functionality. XMLBeans is a facility that constructs Java classes from XML Schema and allows very easy, direct and powerful manipulation of XML documents in Java. If you place an XML Schema (XSD) file into a schema project, the XMLBeans schema compiler is automatically run on the schema and the resulting JAR file is automatically placed in the Libraries folder of the application. The Java classes in the JAR file are accessible to all projects in the application. For example, a web service in a web service project in the application can reference a schema as the input type of one or more of its methods and can automatically access incoming XML documents via the XMLBeans Java APIs.

The SamplesApp samples application contains a sample Schema Project named Schemas. It contains XML Schemas used by various samples in the SamplesApp application. Note: For XML Schemas to be available in a business process, the schemas must be imported into a Schemas project in your integration application. To learn more about using XML Schemas in integration applications, see Guide to Data Transformation.

Portal Project

Portal projects are available in WebLogic Workshop Platform Edition. Portals are used to provide a single point of access to enterprise applications and information that can be based on user, group and role attributes.A Portal project is similar to a Web project in that it is used to expose enterprise application logic via a user interface. Portal projects usually contain Java Server Pages (JSPs), and they provide additional capabilities, in addition to those available in Web projects, that allow developers to define portal Web sites.

Note: A Portal project is a J2EE web application and supports the creation of Web services, page flows and JSPs. The difference between a Portal project and a Web or Web Service project is the set of supporting files the project initially contains. Portal projects contain additional files that support creation of portals.

Datasync Project

Datasync projects are available in WebLogic Workshop Platform Edition. A Datasync project is used to develop and manage general purpose portal services that are used in the development of personalized applications and portals. These portal services include user profiles, user segments, events, request

properties, session properties, content selectors, placeholders, and campaigns. A Datasync project called data is generated when a Portal application is created.

Process Project

Process projects are available in WebLogic Workshop Platform Edition. A business process orchestrates the execution of business logic and the exchange of business documents among back-end systems, users and trading partners (systems and users) in a loosely coupled fashion. A Process project typically contains business process (JPD) files, control files and transformation files.

When to Create a New Project

As you develop an application, you may need to create new projects within the application for the following reasons:

To separate unrelated functionality

Each project should contain components that are closely related to each other. If, for example, you wanted to created one or more web services that expose order status to your customers and also one or more web services that expose inventory status to your suppliers it would make sense to organize these two sets of unrelated web services into two projects.

To control build units

Each project produces a particular type of file when the project is built. For example, a Java project produces a JAR file. If you want to reuse the Java classes contained in the Java project from multiple components, it would make sense to segregate the Java classes into a separate project and reference the resulting JAR file from other projects in your application.

Libraries and Modules

In addition to projects, each WebLogic Workshop application also contains two folders named Libraries and Modules. These folders can contain compiled Java code that you want to be available to the components of the application. The products of the various project types are automatically placed in the Libraries or Modules folder as appropriate. For example, the JAR file containing the XMLBeans Java classes derived form the XML Schemas in a Schema Project is automatically placed in the Libraries folder. However, you may also copy additional JAR files directly into the Libraries or Modules folders to make them available to the rest of your application.

The Libraries and Modules folders both place their contents on the application's Java class path. The main difference between the Libraries and Modules folders is that the contents of the Modules folder are automatically deployed to the appropriate instance of WebLogic Server. For example, when you build an EJB Project, the EJBs in the project are compiled and placed in a JAR file, which is then copied to the Modules folder and thereby automatically deployed to the server. The Libraries folder is equivalent to the APP-INF/lib directory of a J2EE Enterprise Application.

Security Roles

A WebLogic Workshop application also may define security roles, which are a facet of the J2EE security framework based on security roles, principals and groups.

A human resources application might define the following categories of users: an administrator may perform any operation, including configuring the application itself; a manager may perform HR operations on employees (add, delete, adjust compensation, etc.); and an employee may access a subset of his or her own HR records. Each of these user categories is called a security role, an abstract grouping of users that is defined by the designers of the application. When the application is deployed, an administrator will map the roles to actual security identities in the production environment.

A security role is an application-specific grouping of users, classified by common traits such as job title. When an application is deployed, roles are mapped to security identities, such as principals (identities assigned to users as a result of authentication) or groups, in the production environment. Based on this, a user has access rights to specific components and/or functions of an application based on the security role(s) to which the user's identify is mapped. The link is the actual name of the security role that is being referenced.

Following this model of role-based security, application components may be configured to allow or restrict access based on security roles. The application components do not (and should not) concern themselves with specific user or group identities. By abstracting security to roles, the actual configuration of an application's security settings can occur at runtime and requires no changes to the application code. In fact, J2EE allows configuration of security to a fine level of detail purely via declarative means by using files called deployment descriptors, so the application code doesn't even have to be aware of the actual security roles that are defined.

WebLogic Workshop allows you to define the security roles that will be used in your application. When your application is deployed, the security roles you have defined are deployed with it. If you have defined users and groups for test purposes in your development environment, those definitions are not deployed with your application. This eases testing of security configurations in the development environment but avoids the risk of leaving security roles in your application when it is deployed.

Cleaning Applications and Projects

Sometimes when you build an application or project, WebLogic Workshop does not update all of the appropriate build files. As a result, stale artifacts can exist between builds. This could happen for any number of reasons like moving or deleting files while WebLogic Workshop is closed. If you believe that any of your projects are exhibiting strange behavior, you can use the Clean utility to ensure that WebLogic Workshop removes all outdated build files and references. After cleaning, you can re-build the application or individual project and be sure that each build file is fresh.

To clean an application:

From the Application tab in WebLogic Workshop, right-click the application folder and select Clean Application.

To clean a project:

From the Application tab in WebLogic Workshop, right-click on the project folder representing the project you would like to clean and select Clean.

WebLogic Workshop File Types

This topic lists the file types you will encounter in your use of WebLogic Workshop. WebLogic Workshop Application Developer Edition File Types

You may use a variety of files to create your application in WebLogic Workshop, some of which you may not be familiar with. The key file types you may encounter in WebLogic Workshop Application Developer Edition are:

EJB file, or Enterprise Java Bean. An EJB file contains the Java implementation class for an EJB, with Javadoc annotations that configure the EJB.

JCS file, or Java Control Source. A JCS file contains the Java implementation class for a Java control type. There is only one JCS file per Java control. If the Java control is extensible, there may be many JCX files that extend the Java control.

JCX file, or Java Control eXtension. A JCX file is a local extension or customization of a Java control. For example, the Database control is defined once in a JCS file, but a local JCX file in an individual project defines the data source and operations for that particular instance of the control.

JPF file, or Java Page Flow. A JPF file contains the Java implementation class for a page flow, together with Javadoc annotations that configure and control the behavior of a web application. A page flow is a controller and a collection of JSPs. The controller coordinates a user's course through the JSPs depending on changes in state as the user progresses. Page flows also enable you to bind application data to user interface components in the JSPs and to access application logic and data via Java controls.

JSP file, or Java Server Pages. The JSP file type is defined by the J2EE Specification. WebLogic Workshop defines custom JSP tag libraries that allow JSP files to reference Java controls and page flow actions. A related file type is the JSPF file, which stands for Java Server Page Fragment. JSPF files are used to hold snippets of JSP code that can be included in other JSP files. There are many sample JSP files in the WebApp project of the SamplesApp sample application installed with WebLogic Workshop.

JSX file, or JavaScript with Extensions. A JSX file can contain ECMAScript (formerly called JavaScript) for manipulating XML. The functions in the JSX file are called from with XML Maps in a web service. WebLogic Workshop provides an extended ECMAScript language with support for XML as a native type, making XML processing in script very straightforward.

JWS file, or Java Web Service. A JWS file contains the Java implementation class for a web service, with Javadoc annotations that enable specific web service features. There are many sample JWS files in the WebServices project of the SamplesApp sample application installed with WebLogic Workshop.

WSDL, or Web Services Definition Language. WSDL files describe the interface of a web service to consumers of the web service. WebLogic Workshop can easily generate WSDL files for your web services, and can consume WSDL files for external web services so that you may access them from your WebLogic Workshop applications.

XMLMAP files. XML map files describe how XML should be mapped to Java, and vice versa, for a web service.

XQ files, also known as XQuery maps, contain queries written in the XQuery language. These queries contain transformations that convert data between XML, non-XML, Java classes, and Java primitive data sources. You can generate these queries using the provided mapper and use these queries to create business process and web service transformations.

XML files, or Extensible Markup Language files contain XML data that you can use as input to transformations.

XSD files, or XML Schema Definition files contain a schema that describes XML data. Importing an XSD file into a WebLogic Workshop application allows you to use imported XML data types in transformations.

CTRL files, or control files (deprecated). In WebLogic Workshop 7.0, control extensions were defined in CTRL files. CTRL files have been deprecated but are still supported in WebLogic Workshop 8.1. The functionality formerly provided by CTRL files is now provided by JCX files.

WebLogic Workshop Platform Edition File Types

In WebLogic Workshop Platform Edition, you may encounter the following additional file types:

WebLogic Integration File Types

CHANNEL file. The Message Broker provides typed channels to which messages can be published and to which services can subscribe to receive messages. A message broker channel has similar properties to a Java Message Service (JMS), but is optimized for WebLogic Integration processes, controls, and event generators. Channel files define the Message Broker channels in an application. To be visible to other application components, channel files must be placed in a Schemas project in your application.

To learn more about Message Broker channels, see Publishing and Subscribing to Channels.

DTF file, or Data Transformation Format. A DTF file references reusable data transformation methods which convert data from one format to another. For example, XML data can be transformed from XML data valid against one XML Schema to XML data valid against a different XML Schema. Sample DTF files are available in the following applications: Tutorial:

Process Application and New Process Application. (For example, if you create an application based on the Tutorial: Process Application, the TutorialJoin.dtf is available in the application.) These applications are available from File->New->Application in the WebLogic Workshop menu bar.

To learn more about data transformations, see Guide to Data Transformation.

For a tutorial on building data transformations, see Tutorial: Building Your First Data Transformation.

JPD file, or Process Definition for Java. A JPD file contains the Java implementation class for a WebLogic Integration business process, with special annotations that configure the business process. Sample business processes are available in the following applications: Tutorial: Hello World Process Application, Tutorial: Process Application, New Process Application. These applications are available from File->New->Application in the WebLogic Workshop menu bar.

To learn more about business processes, see Guide to Building Business Processes.

For a tutorial on building building business processes, see Tutorial: Building Your First Business Process.

MFL file, or Message Format Language describes and constrains the content of non-XML data. An MFL file defines a schema for non-XML data. You can use the the Format Builder to create MFL files at design-time. Importing an MFL file into a WebLogic Workshop application allows you to use the imported non-XML data types ( defined by the MFL ) file in transformations.

To learn more about working with MFL data, see Assigning MFL Data to XML Variables and XML Data to MFL Variables.

XSL file. This is basically an XSLT file with an XSL extension. XSL stands for Extensible Stylesheet Language. This language is defined by the W3C that supports the use of stylesheets for the conversion of XML data. When a Transformation method of type XSLT is invoked, the XSLT processor invokes the transformations defined in the associated XSLT file.

WebLogic Portal File Types

CAM file. Campaigns provide a container for executing scenarios to offer personalized content to users.

EVT file. Event property sets are used to define the events available for personalization services.

PLA file. Placeholders are used to display targeted media to users. In addition, event and behavior data can be tracked via event services.

PORTAL file. A portal is an aggregation of applications and information in a common, coherent user interface.

PORTLET file. A portlet provides a user interface to applications and information.

REG file. Request property sets are used to define the attributes available in the HTTP request

SEG file. User segments represent a business rule to classify users based upon their profile, request, session attributes as well as date and time conditions.

SES file. Session property sets are used to define the attributes available in the HTTP session.

SET file. Content selectors are a business rule used to retrieve content based upon user profile, request, session attributes as well as date and time conditions.

USR file. User Profile property sets are used to define the attributes available in a user’s profile.

Debugging Your Application

You can use the WebLogic Workshop integrated debugger to debug your application. The debugger allows you to set breakpoints, step through your code line-by-line, view local variables, set watches on variables, and view the call stack and exception information.

There are a variety of properties that can be set for the debugger. Some are set on a project basis, while others apply only to Java and Control Projects.

You can use the debugger on runnable files, non-runnable files, non-Workshop enabled servers, and projects developed against a remote server. You can also attach to JUnit and use the JUnit functionality in conjunction with the Weblogic WorkShop Debugger.

Using the Debugger

In order to debug an application, you must have a way to exercise the application as a real client would. WebLogic Workshop includes a Test Browser in which you may test Workshop web applications and web services. When you run a web application or web service, the Test Browser automatically loads Test View, a tool for exercising the application.

To start the debugger, click the Start button on the toolbar or press Ctrl-F5. To pause debugging, click the Pause button on the toolbar. To stop debugging, click the Stop button on the toolbar.

When the debugger is started, the WebLogic Workshop Debugger command window is opened for the debugger proxy. This window must remain open in order to use the debugger. If you close this window, your breakpoints will not be hit when you test your application.

While your application is running in the debugger, it is unavailable to clients other than the Test Browser.

To debug your project, you will use breakpoints, the commands that allow you to navigate the code, and the debug windows, which show information about variable values, how the program is running, and what code is executed.

Breakpoints

Breakpoints allow you to halt execution at a specified point in the program so you can observe information about its operation. When you halt execution at a breakpoint, you can step through the program line-by-line, step over a breakpoint, and use the debug windows to change values or execute arbitrary code.

The types of breakpoints you can set include:

Line Breakpoints - halts execution at the line of code before the breakpoint

Exception Breakpoints - halts execution when an exception occurs

Method Breakpoints - halts execution as soon as a specified method is called

Taglib Breakpoints - halts at the taglib method being implemented

JSP Breakpoints - used with JSP files only

To create Exception and Method breakpoints, select Debug-->Create Breakpoint and enter the appropriate settings in the Create Breakpoint dialog.

To create a Line breakpoint, put the cursor on the line of code where you want to halt execution and click the Toggle Breakpoint button on the toolbar.

To clear all breakpoints at once including exception breakpoints in the project, click the Clear All Breakpoints button on the toolbar, or press Ctrl-F9.

Using the Debugging Commands

Once execution is halted on a breakpoint, you can use one of the following commands to continue executing your code with the debugger. All of these commands are available on the toolbar and on the Debug menu.

Step Into: The Step Into command continues execution line-by-line, beginning with the next line of code. Use this command if you want to debug your code one line at a time.

Step Over: The Step Over command executes a method call without debugging that method, and halts execution on the next line. Use this command if you know that the code in a method works and you don't need to step into it.

Step Out: The Step Out command finishes executing a method and returns execution to the procedure that called it, halting on the line immediately following the method call. Use this command if you have stepped into a method and you don't want to continue stepping all the way through it.

Continue: The Continue command resumes execution until another breakpoint is encountered or the procedure has completed.

Export Threads: The Export Threads command, found in the Debug menu, creates and opens a text file that contains the call stacks of all of the threads that are running. This is a convenient way to save or share the current threads in the event of a deadlock or other threading problem. The command is only active when the debugger has thread information.

Note that if you step into a line that contains more than one statement, all of the statements on that line will be executed when you step to the next line.

Debug Windows

The debug windows provide information about values and conditions in your code while you're running it in the debugger. There are several to choose from:

Locals Window - shows variables that are in scope

Watch Window - displays the value of a specified variable while debugging

Stream Window - shows output stream for JSPs

Immediate Window - allows you to execute code while debugging

Call Stack Window - shows the methods called to get to the point at which execution halted

Threads Window - shows information about currently executing threads

Breakpoints Window - lists currently set breakpoints

To view one of the debug windows, choose Debug Windows from the View menu, and select the desired window. For more detailed information about the debug windows,

Debugging Properties

Several debugging options can be set on a project scope. The debugging options for each project in an application are independent, and are not set on an application basis.

Debugging properties for a project can be set on the Project Properties dialog box. To change them, pull up the project properties by either right-clicking the project folder in the Application tab and selecting Properties from the context menu, or by going to Tools-->Project Properties-->[Project_Name], then select Debugger in the pane on the left.

Alternatively, project debugging properties can be set by editing the WORK configuration file associated with the project.

Some project debugging properties apply only to specific types of projects.

Smart Debugging

Smart debugging lets you focus on debugging your code and not platform code. When you step through code, you stay in your own code. When smart debugging is enabled, you can specify classes that the debugger will automatically step through. Typically, the filtered classes are part of the WebLogic Platform. For example, if you step into a method that's part of WebLogic Server and that method eventually calls your own code, the debugger will step directly into your code. For web application projects, this should almost always be left on.

Smart debugging is enabled by default, and a default list of classes is generated automatically. You can disable filtering on parts of the class list by checking or unchecking the group of classes in the debugging properties dialog. For example, if you uncheck XML classes, the debugger will step into platform classes that support XML.

With version 8.1 SP2 or higher, you can add, remove, and edit the class list. The asterisk (*) wildcard can be used to specify packages and subpackages.

Build Before Debugging

This option specifies whether the project should be rebuilt before it is run in the debugger. For web applications, only the current file is rebuilt before running. For Java projects, the entire project is built before running.

By default, the Build before debugging option is enabled.

Pause All Threads After Stepping

This option specifies which threads are shown in the Threads window after stepping in the debugger. All threads are always suspended after hitting a breakpoint, but by default only the thread in which you are stepping is visible. By default, this option is disabled to provide better performance, so other threads will not be visible in the threads window. If you choose not to suspend all threads after stepping, you can still view them on demand using the Pause command.

Java and Control Project Options

Process Settings

The Create new process and Attach to process radio buttons specify whether the debugger runs the application is run locally or attaches to a remote process. These settings apply only to Java and Control projects.

Create new process settings

When this option is selected, the debugger starts a new Java Virtual Machine for the application when you click Start. The following options can be set for this process:

Main class: The name of the class containing the main method that is the entry point for the application.

Parameters: Arguments that are passed to the main method.

VM parameters: Arguments that are passed to the virtual machine when it starts. These arguments may include -D and -X virtual machine options.

Home directory: The directory in which to start the Java application.

Application classpath: Classpath used by the virtual machine.

Automatically append Library JARs: When this option is enabled, all of the JARs specified in the Libraries folder are appended to the classpath.

Automatically append server classpath: Then this option is enabled, all of the JARs that are specified in the"Default server classpath" list in Tools-->WebLogic Server-->Server Properties are appended to the classpath.

Attach to process

When this option is selected the debugger is attached to a specified Java virtual machine that is already running and is configured to accept a debugger when you click Start.

Socket: Connects to the virtual machine over the TCP/IP connector. You must specify the port on which the VM is listening. If blank, the server defaults to localhost.

Shared memory: Connects to the virtual machine over the shared memory connector. You must specify the memory address on which the VM is listening.

Debugging Scenarios

The WebLogic Workshop integrated debugger can be used in many debugging scenarios, as listed in this topic.

Remote Debugging

If you're developing against a remote server, you can also debug against that remote server. Breakpoints and other debugging information will be stored on the local machine.

You can also debug on a managed server, as described below.

Debugging JSP Pages

Be aware that browser caching is always turned off when you are debugging. To turn caching on while you are debugging, place the following scriptlet in your JSP pages.

<%

response.setHeader( "Cache-Control", null );

%>

Note that browser caching is the default behavior when your web application is deployed to a production server. You do not need to take special measures, such as the scriptlet above, to turn on caching on a production server.

Debugging EJBs

The debugger supports debugging EJBs regardless of whether they have been developed within WebLogic Workshop. They can be debugged locally or remotely.

Use the following procedure to attach the debugger to an EJB:

Open the source in Workshop

From the Tools menu choose Project Properties.

In the Debugger tab, choose Attach to Process.

Enter the debug port number (8453 by default) and server name or IP address.

Click Start.

Set breakpoints as needed and start debugging.

Debugging on a Non-Workshop-Enabled Server

To debug a project on a server not configured as a Workshop Server, open the Project Properties dialog box for the project you want to debug. On the Debugger tab, choose the "Non Workshop Server" radio button, and enter the debugging port number (8453 by default), the Http port number, and the name or IP address of the remote server.

Debugging on a Managed Server

To debug a project on a managed server, set up the front end host and port for the cluster and/or managed servers. Cluster servers can be set up using a proxy. Run all of the managed servers except one, and the admin server with nodebug on the start line. Do all of your debugging against the managed server.

Debugging Unrunnable Files

Some files cannot be directly run by WebLogic Workshop; these include servlets, custom Java controls, Java files, and so on. Nevertheless, you can still set and hit breakpoints in these files. For example, to debug a servlet, set breakpoints in the servlet source code, add a JSP page to your project, run that JSP page (this will start the debugging process), and then enter the servlet's URL directly into the browser's address bar. You will now be able to halt at breakpoints in the servlet code. To debug custom Java controls or Java files, set breakpoints in the source code of those files, and then run a web service or some other runnable file that calls into the Java control or Java file.

Starting Two Debugging Proxies in the Same Domain

If you start two server instances in the same domain (for example, using the start up script [BEA_HOME]/weblogic81/samples/domains/portal/startWebLogic.cmd), the second server will fail with a TransportException.

ERROR: Proxy already running...

weblogic.debugging.comm.TransportException

at weblogic.debugging.comm.ServerConnectInfo.createTransport()Lweblogic.

debugging.comm.CommTransport;(ServerConnectInfo.java:63)

The failure is caused by the debugging proxy, which attempts to open the same server socket port already used by the first server. To start the second server running on a different port, send a port number parameter to (1) the WebLogic Workshop IDE, (2) the server, and (3) the debugger. These are described below.

To Set the Port Number on the WebLogic Workshop IDE

Add the following parameter to [BEA_HOME]\weblogic81\workshop\workshop.cfg.

-Dworkshop.debugProxyPort=PORT_NUMBER

To Set the Port Number on the Server

Add the following parameter to the server startup script (for example, [BEA_HOME]\weblogic81\samples\domains\workshop\startWebLogic.cmd/.sh).

-Dworkshop.debugProxyPort=PORT_NUMBER

To Set the Port Number on the Debugger Process

Add the following parameter to the server startup script (for example, [BEA_HOME]\weblogic81\samples\domains\workshop\startWebLogic.cmd/.sh).

-serverport=PORT_NUMBER

Testing Your Application

Testing your application goes hand-in-hand with debugging. The test facility that comes with Weblogic Workshop runs in a browser window and is known as Test View.

In addition to Test View, you can use JUnit for testing from within Workshop.

Follow the links below for more information on using Test View and JUnit.

Managing the Build Process

The topics in this section discuss the WebLogic Workshop build environment and provides tips on how to optimize your build process.

Understanding the Build Process

Describes when and why to build your project or application. Understanding the build process better can help you streamline your iterative development effort.

Using the Build Process More Efficiently

Provides tips on how to build applications and projects efficiently. You can significantly reduce build times by making a few small configurations to the build environment and following a few of the best practice guidelines outlined in this document.

Customizing the Build Process

Introduces the scripts that WebLogic Workshop uses to perform application and project level builds. This topic describes how you can export, edit and deploy these scripts to create a custom build process.

How Do I ...?

Contains topics that guide you through the various tasks associated with managing the WebLogic Workshop build process.

Understanding the Build Process

Building your WebLogic Workshop application can be a time-consuming part of the iterative development process. By understanding when and how to build your application and its respective projects, you can streamline the build process for your application.

When Do I Need to Build My Project?

How often you need to build your project depends on what type of project you are using and what you are doing, but you may not need to build the project as often as you think.

Web Service, Page Flow, JSP, and JPD Files

If you are developing and testing web service (JWS), page flow (JPF), JSP, and JPD files in a Web or Web Service project, you don't need to build the project that contains them at all until you are ready to deploy the project. You can simply run the file in Test View to build and test them iteratively. WebLogic Workshop will automatically build any dependencies of that file for you on an as-needed basis.

Web and Web Service Projects

You only need to build Web and Web Service projects when you are ready to deploy those projects to a server that is not running in iterative development mode (that is, a server that was started with the noiterativedev flag passed to the startWebLogic command).

You can specify that Web and Web Service projects be built incrementally when you do build, rather than cleaning the project each time, by setting the Use Incremental Build property for the project. This can speed up the process of making changes to a web application that is running on a production server. Note that there are a small number of situations where incremental build will not detect file changes (e.g. final static variables, changes in external XML files). In those cases, a clean build will be necessary to reflect the current state of the project. For information on setting the Use Incremental Build property, see Using the Build Process More Efficiently.

Java, Control, EJB, and Schema Projects

Java projects, Control projects, EJB projects, and Schema projects are similar in that the result of building any of these projects is a JAR file that is written to the application's APP-INF/lib folder, or in some cases, the APP-INF/classes folder. These JAR files can then be used by other projects within the application. You should build these projects when you need to update the JAR files so that the latest changes are available to any projects that are using them.

When you build one of these projects, WebLogic Workshop checks to see that the JAR file is indeed out-of-date. If the JAR file is up-to-date, WebLogic Workshop doesn't build the project.

When Do I Need to Build My Application?

You need to build the entire application only when you are ready to deploy your application to a server that is not running in iterative development mode (that is, a server that was started with the noiterativedev flag passed to the startWebLogic command).

Production Build

When you are ready to deploy your application to a production server, you most likely want to perform a clean operation and then build the full application to generate an EAR file. This approach ensures that you have a consistent means of controlling the quality of your production application, and that you will not deploy unnecessary build artifacts to the production server. To perform a production build, you can use the Build->Build EAR command in the IDE, or the wlwBuild command from the command line.

The Build EAR menu command and the wlwBuild command perform a clean operation and build the complete application as they did in prior releases. If a project has enabled incremental build or disabled JSP pre-compilation, those settings are ignored when building an EAR using Build EAR or wlwBuild.

Developer Testing

If you are developing your application iteratively and testing it in a local or shared environment, you may want to build the EAR file incrementally in order to save time when testing frequent changes. Building

an EAR incrementally affects only Web and Web Service projects. When you build the EAR file incrementally, only those files and dependencies that have changed since your last build are built. No clean operation is performed, and existing build artifacts are not removed. Incremental build can speed up the process of deploying and testing changes to a Web or Web Service project.

Incremental build applies only to Web and Web Service projects where the Use Incremental Build property for the project is set to true. To build an EAR file where projects are built incrementally, use Build->Build EAR (Incremental) from the IDE, or specify the –incremental command line option when building from the command line with the wlwBuild command. For more information on building incrementally, see Using the Build Process More Efficiently.

When Do I Need to Clean Before Building?

The clean operation cleans all build artifacts resulting from a previous build of a project or application. It's a good way to "start over" so that you know that your build output includes only the most up-to-date files based on your source code. However, you don't need to perform a clean operation every time you build. You should clean your project or application in the following scenarios:

Streamlining Project and Application Size

When you rename or delete files in your application, the corresponding build artifacts are not deleted until you perform a clean operation. These extraneous build artifacts are generally harmless, but it's a good idea to clear them out now and then so that they don't slow down server startup and redeployment.

Building the Production Quality Application

Before you deploy your application to a production environment, you will probably want to perform a clean operation followed by a complete build in a controlled environment. In this way you can ensure that you have a formal, repeatable build process that you use every time you deploy an application to production.

Restoring the Server State

Occasionally a project can get out of sync with the server, and not function properly. When this happens, you should perform a clean operation to restore the state of the server.

Customizing the Build Process

WebLogic Workshop provides you with full control over the way you build JAR and EAR files from WebLogic applications and their projects. WebLogic Workshop accomplishes this by giving you complete access to the Another Neat Tool (ANT) XML build files that it uses to create these archives. You can customize the contents of these build files to specify the order in which WebLogic Workshop carries out build tasks, introduce new logic in between build steps, or integrate multiple build processes. WebLogic

Workshop gives you access to both application-level or project-level ANT build files. The following sections discuss how to edit and use both files to customize your WebLogic Workshop build process.

Customizing Project-Level Builds

If you want to customize the way WebLogic Workshop builds an individual project, you can use the WebLogic Workshop IDE to export the ANT build file that WebLogic Workshop uses to build that project. WebLogic Workshop exports an ANT XML build file entitled exported_build to the home directory of that project. Change this file using syntax that conforms to the Apache ANT Specification. When you are through making your changes, simply reference that file in the project settings of the WebLogic Workshop IDE. When you build the project, WebLogic Workshop will use that custom build file to create the project JAR. For details on customizing a WebLogic Workshop project build, see How Do I: Use a Custom Ant Build for a Project?

If you want to automate the build process, simply use the BEA_HOME/weblogic81/workshop/wlwBuild.cmd and use the appropriate command line switch to specify that you only want to build that individual project. For more information on this command, see wlwBuild command.

Application-Level Builds

If you want to customize the way WebLogic Workshop builds an entire application, you can also use the WebLogic Workshop IDE to export the ANT XML build file that WebLogic Workshop uses to build the application. Like the project-level ANT file, WebLogic Workshop exports an XML file entitled exported_build to the home directory of the application. Use syntax that conforms to the Apache ANT Specification to execute logic from other archives, alter the order of project builds based on some condition, or make any other custom adjustment. Unlike project builds, you cannot execute this build file from within the WebLogic Workshop IDE. Instead you must execute the file using an ANT script. For more information on customizing an application build, see How Do I: Call wlwBuild.cmd from an ANT build.XML file?

Excluding Files From an Application-Level Build

When you build a WebLogic Workshop application, the Workshop compiler creates an Enterprise Archive (EAR) file. You can control what files WebLogic Workshop includes in that EAR by editing the excludefilesFromEar attribute in the applications .work file. The excludefilesFromEar attribute is shown below in red:

Note that WebLogic Workshop automatically sets the value of this attribute to [default]. This excludes file types with the extensions app, ctrl, dtf, ejbbean, java, jcs, jcx, jpd, jpf, jsx, jwf, jws, and wlbean by default.

How Do I: Compile a Single Java File?

To selectively compile a single JAVA file, you can integrate a custom compilation script into the Workshop IDE by declaring the custom script as an "external tool". You can then pass single JAVA files from the IDE to the custom script.

Declaring a Custom Compilation Script as an "External Tool"

On Windows operating systems, open the the Workshop Preferences file located at C:\Documents and Settings\[Windows_user_name]\.workshop.pref.

Edit the element <component name="workshop.workspace.tools.CustomToolAction"> to include your custom compilation script. This element determines the options that appear in the menu bar Tools-->External Tools.

<component name="workshop.workspace.tools.CustomToolAction">

<node name="javac">

<option name="capture" value="true" />

<option name="command" value="compile.cmd "${file.path}"" />

<option name="directory" value="C:\build_scripts" />

<option name="interactive" value="false" />

</node>

</component>

The element <node name="javac"> causes a menu option named "javac" to appear on the menu bar Tools-->External Tools.

The element <option name="directory" value="C:\build_scripts" /> tells Workshop where to look for your build script (you can place the build script in any local directory).

The element <option name="command" value="compile.cmd" "${file.path}" /> tells Workshop to pass the currently open file to the build script.

Place the Custom Compilation Script in the Appropriate Directory

Save your build script in the directory specified in the element <option name="directory" value="C:\build_scripts" />. Below is a build script that you can use as a template.

compile.cmd

set PATH=D:\jdk1.4.2_04\bin;

set CLASSPATH=MyClasses

set CLASS_DIR=C:\bea\weblogic81\samples\workshop\SamplesApp\WebApp\WEB-INF\classes

javac -d %CLASS_DIR% -classpath %CLASSPATH% %1

echo compiled %1

popd

To compile a JAVA file, open the file in the Workshop IDE, and select Tools-->External Tools-->javac. The compile results will be displayed on the javac tab.

How Do I: Use a Custom Ant Build for an Application?

WebLogic Workshop uses a standard Ant build process for all applications. You can create a custom Ant build file for an application that extends the standard build process or uses different build targets altogether. If you want to extend or modify the standard build process, you should first export the standard application build file and begin by modifying that file.

To Export the Standard Application Build File

Choose Tools-->Application Properties to display the Application Properties dialog.

In the left-hand pane, select Build.

In the Build Type pane, click Export to Ant File. A dialog appears informing that the exported_build.xml file has been stored in the root of the application folder. Click OK.

The exported Ant file contains a set of standard tasks and targets for managing the build for your application.

Note the class workshop.core.WlwBuildTask called by the "wlwBuild" task is the same class called by the command line tool wlwBuild.cmd.

<taskdef name="wlwBuild" classname="workshop.core.WlwBuildTask"

classpath="${weblogic.home}/workshop/wlw-ide.jar"/>

The most important target in the Ant file is the "build" target.

<target name="build">

<!-- Builds the full application creating an ear at the specified location.

The server classpath parameter is used, but may be omitted if the server home directory

configured in Workshop is accessible. -->

<wlwBuild work="${app.dir}/${work.file}" serverclasspath="${server.classpath}">

<build outputdir="${output.dir}" outputfilename="${output.file}"/>

</wlwBuild>

</target>

Note that the following parameters are available for the "build" target:

project: String. Name of a specific project within the application to build. If omitted, the entire application will be built.

outputdir: String file path. Directory where build output file(s) will be placed. Defaults to application directory. May not be applicable for some types of project build.

outputfilename: String file path. Filename to use for output archive. Defaults to appname.ear. May not be applicable for some types of project build.

nodebug: Boolean value. Turns debugging information on or off. If no value is specified, the value is set to false.

noear: Boolean value. Specifies whether an EAR file should be generated for the application build. If no value is specified, the value is set to false. Not applicable for a project build.

To Create a Custom Ant Build File

You can use the standard exported build task and add additional build (sub)targets, or you can create a new ant file. To add a new task, you must use the <taskdef> element:

<taskdef name="myTask" classname="myTask" classpath="AllMyClass.jar"/>

Use the classpath attribute to specify the physical location of the JAR file as shown above, or you can specify the location when you change the project properties to use the custom build file as is described next.

You can also create a custom build process for an individual project within your application. Again, you should begin by exporting the standard build file and modifying that file.

To Export the Standard Project Build File

Open the target application in WebLogic Workshop.

From the Tools menu, select Project properties, then the target project name.

In the Project Properties dialog, from the left-side navigation panel, select the Build node.

In the section labeled Build Type, click the Export to Ant file button.

An Ant file named exported_build.xml is generated and placed in the project's root directory, e.g., BEA_HOME/weblogic81/samples/workshop/SamplesApp/WebServicesexported_build.xml.

To Use the Project Build File

Choose Tools-->Project Properties--><projectname> to display the Project Properties dialog.

In the left-hand pane, select Build.

In the Ant Settings area, click Browse, navigate to the new build file and click Open.

If your build file contains a new task definition without a classpath attribute, click Add JAR to specify the location of the Ant task. Navigate and select the file, then click Select JAR.

In the Build Type area, select Use Ant Build.

From the Build Target drop-down list, select the build target.

Click OK.

The Ant window will now appear in WebLogic Workshop, listing the various targets. From this window you can run a target by double-clicking it.

How Do I: Call wlwBuild.cmd from an Ant build.xml file?

The following topic explains how to create an Ant task that calls the command line tool wlwBuild.cmd. wlwBuild.cmd is used to create application-level EAR files or project-level JAR files for deployment to a production server.

To create an Ant build.xml file, you can either auto-generate a build.xml file or you can write the file by hand.

To auto-generate an Ant build.xml file for the application

Open the target application in WebLogic Workshop.

From the Tools menu, select Application properties.

In the Application Properties dialog, from the left-side navigation panel, select the Build node.

In the section labeled Export, click the Export to Ant file button.

An Ant file named exported_build.xml is generated and placed in the application's root directory, e.g., BEA_HOME/weblogic81/samples/workshop/SamplesApp/exported_build.xml.

The generated Ant file contains two tasks by default: "build" and "clean". When calling the build file from the command line, use the -f flag to name the file exported_build.xml:

C:\bea\weblogic81\samples\workshop\SamplesApp>ant -f exported_build.xml build

To build selected projects with the application, modify the <build> element within the exported_build.xml file. By adding the attribute project="Schemas", only the Schemas project will be build:

<target name="build">

<!-- Builds the full application creating an ear at the specified location.

The server classpath parameter is used, but may be omitted if the server home directory

configured in Workshop is accessible. -->

<wlwBuild work="${app.dir}/${work.file}" serverclasspath="${server.classpath}">

<build outputdir="${output.dir}" outputfilename="${output.file}" project="Schemas"/>

</wlwBuild>

</target>

See the documentation within the exported_build.xml file for more information about specifying output directories, output file names, etc.

You can also export an Ant build.xml file for building an individual project in much the same way as you do for the application.

To auto-generate an Ant build.xml file for a project

Open the target application in WebLogic Workshop.

From the Tools menu, select Project properties, then the target project name.

In the Project Properties dialog, from the left-side navigation panel, select the Build node.

In the section labeled Build Type, click the Export to Ant file button.

An Ant file named exported_build.xml is generated and placed in the project's root directory, Integrating with Source Control Systems

WebLogic Workshop integrates directly with the following source control systems: CVS, Perforce, and IBM Rational ClearCase. Once you have added the files in your WebLogic Workshop application to a respository managed by one of these source control products, you can check files in and out using commands available in WebLogic Workshop.

Enabling Source Control Integration in WebLogic Workshop

If you are part of a team development project and the application you are working on is already in a source control repository, you can simply point at that repository from WebLogic Workshop to enable

source control integration from within the IDE. After you enable source control integration, the source control module's commands are available to you in WebLogic Workshop. For example, when you right-click on a file you will see a menu item for the name of the source control module (CVS, Perforce, or ClearCase), and beneath that menu item, the commands available for working with the file.

For more information on enabling source control integration with one of these source control systems,

To Configure WebLogic Workshop for Source Control Integration

Configure your source control system as advised by your system administrator. In most cases you will need at least a client configuration that specifies how your computer interfaces with the source control system.

From the Tools menu, select Application Properties.

Click the Source Control tab.

From the Source control module drop-down, select Perforce, CVS, or ClearCase.

Set the properties for the source control module to map to the configuration on your computer.

If you want to enable source control integration only for a project within your application, or if you have different projects within different source control repositories, you can specify source control settings at the project level. From the Tools menu, choose Project Properties--><projectname>, click the Source Control tab, and clear the Use application's source control settings option.

Using Source Control Commands from WebLogic Workshop

Once you've configured Workshop for source control integration, you can perform commands against individual files in your application or project. There are two ways to execute source control commands:

Right-click the file and choose the name of the source control system you're using -- CVS, Perforce, or ClearCase. The commands available for that file are listed on the submenu.

Open the file in WebLogic Workshop. From the Tools menu, choose your source control system; the available commands are listed on the submenu.

Which Files Should You Add to Source Control?

There are a lot of files in a WebLogic Workshop application, and not all of them need to be checked in. The files which should be checked in are those that are not modified by the build process. These files include source files and some other files that are created with the project but never modified. The project can be built while any of these are read-only (for source control systems that govern read/write access), so that you only have to check out the files that you wish to modify.

The files to add to source control are:

The .work file that represents the application. It appears at the root of the application directory.

All source files that you have added or modified -- JWS, JCX, JSX, JSP, and so on.

Any XML schema files that you have added to the Schemas project.

The files in the Resources folder in a web project.

Any JAR files that you have added to the Modules folder. These files are stored at the root of your application in the file system.

Any JAR files that you have added to the Libraries folder. These files are stored in the APP-INF/lib folder in the file system.

The following files in the WEB-INF folder in a web project: web.xml, weblogic.xml, wlw-config.xml.

The global.app file in the WEB-INF/src/global folder.

The tag libraries that appear in the WEB-INF folder in a web project, if you have page flows and JSP files in your project. These files end with the .tld and .tldx extensions.

The JAR files that appear in the WEB-INF/lib folder in a web project.

The files that are modified by the build process -- compiled classes, for example -- do not need to be added to source control. You can add them, but you'll have to check all of them out each time you build your application. And since many of them are binary files and can't be modified directly, you don't gain anything by keeping them under source control; if you're developing your application as part of a team, putting these files under source control is likely to generate confusion for team members.

The files that you do not need to add to source control are:

Files in the .workshop directory beneath the base application directory

Files in the META-INF directory

Files in the WEB-INF/.pageflow-struts-generated directory in a web application project

Files in the WEB-INF/classes directory in a web application project

Files in the WEB-INF/lib directory in a web application project

JAR files that are generated from a project in your application

Modifying the .work File Under Source Control

There is currently no way to check out the .work file manually from within WebLogic Workshop in the same way that you can check out other files in your application. However, if the .work file is read-only,

and you make a change that requires modifying the .work file, WebLogic Workshop will prompt you to check it out.

Changes to your application which modify the .work file include:

Adding, importing, or deleting a project

Changing settings in the Application Properties dialog.

Changing settings in the Project Properties dialog.

Note: You should be careful about checking in the modified .work file when you are working in a team development environment. When you save the file, WebLogic Workshop may change the server.path variable within the file from a relative path to an absolute path to the server directory on your computer. Since it's unlikely that other users have the exact same absolute path on their computers, the application may not function properly after they sync to your change. Unless you specifically want to check in a change to the .work file, you generally want to revert your changes rather than checking them in. A good way to know is to perform a diff operation between the file that's in the source control repository and the modified file on your local computer. If you do want to check in changes to the .work file, you may need to edit the .work file manually using a text editor to change the server.path variable back to a relative path value.

ClearCase Source Control Integration

WebLogic Workshop integrates with the IBM Rational ClearCase. This topic describes how to put your Workshop application under source control with ClearCase.

WebLogic workshop integrates with these ClearCase products: ClearCase, ClearCase MultiSite and ClearCase LT, versions V2003, V2002 and V4.2.

Setting Up Source Control Integration with ClearCase

WebLogic Workshop supports integration with ClearCase for a Workshop application and all of its projects, or for an individual project with an application. In either case, all of the files of the Workshop application or project must be associated with a single ClearCase Version Object Base (VOB). This restriction also means that:

The mapping between the files in a Workshop application or project and the ClearCase VOB must be defined by a single snapshot view.

The root directory for the application or project must reside beneath the root directory for the ClearCase VOB. If the root directory for the application or project is in a subdirectory of the VOB root directory, then all of the parent directories must also exist in the VOB.

It's possible for a single Workshop application to contain multiple projects that are mapped to different VOBs and have separate associated views.

Note: We recommend that you create a snapshot view in ClearCase to map your Workshop project files to the ClearCase VOB. You may encounter unexpected behavior with Workshop if you are using a dynamic view.

To Add Your Workshop Application or Project to ClearCase

Make sure that you have a snapshot view that provides access to the VOB where your application or project files will reside. If you need help creating this view, see the ClearCase documentation or ask your system administrator.

Create a new Workshop application or project in a directory that is beneath the root directory for the VOB. If you are copying or moving an existing application or project, you should clean it before you add it to source control, so that build artifacts are not added along with source files. To clean an application, select the application name in the Application pane, right-click, and select Clean Application. To clean a project, select the project name in the Application pane, right-click, and select Clean <projectname>.

If you're adding an application to source control, select Tools-->Application Properties, then select the Source Control tab. If you're adding a project, select Tools-->Project Properties--><projectname>, then select the Source Control tab and clear the Use application's source control settings option.

Set the Source control module option to ClearCase.

Set the cleartool directory option to point to the location of the ClearCase cleartool utility. If you accepted the defaults on installation, the directory containing the cleartool utility should look something like C:\Program Files\Rational\ClearCase\bin. Note that you should include the path only, not the file name. The cleartool utility is the command-line utility that WebLogic Workshop uses to integrate with ClearCase.

Set the ClearCase Version option to your server version. Be sure to verify that you have specified the right version, as you may experience problems with ClearCase integration if the version is incorrect.

Set the ClearCase view type setting to snapshot, if you are using a snapshot view.

Set other options in the properties dialog as desired.

When you click OK, WebLogic Workshop will verify the location of the cleartool utility and will verify that the application or project's root directory is beneath the ClearCase VOB. If your view is a snapshot view, WebLogic Workshop will also prompt you to perform an update against the parent directory of the application or project root directory.

Adding Files to ClearCase

After you've configured WebLogic Workshop to integrate with ClearCase, you can add the files in your application or project to ClearCase through the IDE. To add a file, select the file in the Application pane, right-click, and choose ClearCase-->Add or Add and Checkin.

There are some differences between versions of ClearCase in terms of how files and directories are added to source control. These differences are outlined in the following sections:

ClearCase V2003

With ClearCase version V2003, when you add a file to source control, its parent directories are automatically added as elements and checked out. If you add the application or project root directory, the parent of this directory, which is not visible in the Workshop IDE, is automatically checked out. You must use an external ClearCase tool to check this directory back in. If you execute the Add and Checkin command on a file, the parent directories of the file are automatically checked in.

If you execute the Add and Checkin command on a directory, you must check in the parent directories of that directory manually in order to commit the addition.

ClearCase V2002 or Earlier

With ClearCase version V2002 or earlier, all parent directories must already exist in the VOB and must be checked out before you can add a file that resides in a subdirectory. You must check in all checked out parent directories to commit the operation.

Using External ClearCase Tools

In some situations you will need to use external ClearCase tools, such as ClearCase Explorer or the cleartool utility, to perform certain operations on files in your application or project. These operations include: Adding the .work file to ClearCase or checking it in. However, once you've added the .work file to source control, WebLogic Workshop will prompt you to check it out if you make a change that affects the .work file.

Adding, checking out, or checking in the parent directory of the root directory of the application or project. In version V2003 only, this directory will be automatically checked out when the root directory is added to ClearCase, but an external tool is required to check it back in.

Checking in a file that is not the most recent version on the branch.

The ClearCase Find Checkouts utility may be useful in conjunction with WebLogic Workshop. This utility shows all checkouts in the view, including those that are not visible in WebLogic Workshop, like the parent directory of the root directory of the application or project.

Checking Out Files

To check out a file from within WebLogic Workshop, right-click on the file in the Application pane and choose ClearCase-->Checkout.

If the file you are checking out is not the latest version in the VOB, you'll see a warning in the checkout dialog. At this point it's recommended that you dismiss the dialog and update the file before continuing. You can also choose to check the file out and merge your changes in with the head version in the VOB when you submit the file.

Note that you cannot check out a file that is writeable.

Stopping ClearCase Commands

Once in awhile a ClearCase command may fail to finish executing. If this happens, you can halt the command by right-clicking in the ClearCase window and choosing Stop. Once you've enabled ClearCase integration, the ClearCase window is available by choosing View-->Windows-->ClearCase.

Warning: Use caution when halting executing ClearCase commands, as doing so can have unpredictable or undesirable results.

Message Logging

WebLogic Workshop writes diagnostic information to files that you can use to track activities of a WebLogic Workshop application. These logging messages originate from two distinct sources: the run-time environment and the Integrated Development Environment (IDE).

Run-time Environment Logging

IDE Logging

You can use this information to diagnose unexpected behaviors or monitor the general progress of any WebLogic Workshop application. This topic describes how WebLogic Workshop reports diagnostic information and where it writes the information. This topic also explains how you can configure WebLogic Workshop to report additional information to suit your needs.

Run-time Environment Logging

The run-time environment refers to events that happen after you click the start button in the IDE and your application begins to run. These run-time events are logged to three files:

workshop.log

workshop_errors.log

workshop_debug.log

These three files are always co-located in the root directory of the domain under which your WebLogic Workshop application runs. For example, if you are running the SamplesApp application that ships with WebLogic Workshop, you can find this file in the /samples/domains/workshop/directory. This is because the SamplesApp application runs in the workshop domain.

workshop.log: WebLogic Workshop automatically writes all internal log messages to workshop.log. If you use log4j to add log messages to your application code, WebLogic Workshop will append those messages to workshop.log as well. For information about adding logging messages to your application code, see workshopLogCfg.xml Configuration File.

workshop_errors.log: WebLogic Workshop writes all warning and error messages to a file named workshop_errors.log.

workshop_debug.log: The workshop_debug.log file contains messages that are only useful to internal BEA developers, support representatives, and quality assurance representatives. You can ignore workshop_debug.log.

Customizing the Way WebLogic Workshop Logs Run-time Messages

You might want to customize the way WebLogic Workshop reports diagnostic information. For instance, you might want to log information to a console or database instead of a file. Perhaps you would like to adjust the way these messages appear in the log file. If you want to have better control over these details, you can do so by editing the workshopLogCfg.xml file. This is WebLogic Workshop's default log configuration file. You can locate workshopLogCfg.xml at /common/lib/.

The workshopLogCfg.xml file defines which run-time libraries report information, the type of information they report, the display format of that information, and the log files to which that information is written. You can customize any of these details by editing workshopLogCfg.xml. Alternatively, you can override the settings in workshopLogCfg.xml by providing your own custom configuration file. For guidance on both approaches, see workshopLogCfg.xml Configuration File.

IDE Logging: WebLogic Workshop also has an IDE logging feature, which logs various events from the IDE, such as events that occur during startup. IDE logging is off by default, but you can turn it on by following the steps in How Do I: Turn On IDE Logging?. These messages can help BEA technical support troubleshoot issues you may encounter when developing applications with WebLogic Workshop. WebLogic Workshop writes IDE-related log messages to a file named ide.log. You can find this file at /workshop/.

Sample

The data shown below is an excerpt from /workshop/ide.log.

DEBUG: extensions=C:\bea\weblogic81\workshop\\extensions

INFO: Registering extension com.bea.portal.ide.CommonServices

INFO: Service com.bea.portal.ide.findrefs.FindRefsSvc registered

INFO: Handler for urn:com-bea-portal-ide:ref-finders registered

INFO: Registering extension workshop.control.ControlServices

INFO: Service com.bea.ide.control.ControlSvc registered

...

...

DEBUG: WorkspaceLoaded: 11063ms

DEBUG: *** CompilerProject constructor 1

DEBUG: getClasspathMapping initiated with 21 item list.

DEBUG: getClasspathMapping returning 21 item map.

SourceLoader roots: 16

DEBUG: Document Panel initialized: 14017ms

DEBUG: Source Load: 2172

INFO: Startup Complete

DEBUG: Loading template file wsrp-producer-project.zip

Because this information is of minimal use to most WebLogic Workshop developers, WebLogic Workshop disables IDE logging by default. If you contact BEA technical support, representatives might ask you to enable logging in order to better diagnose IDE related issues.

Working with Java Controls

WebLogic Workshop provides Java controls that make it easy for you to encapsulate business logic and to access enterprise resources such as databases, legacy applications, and web services. There are three different types of Java Controls: built-in Java controls, portal controls, and custom Java controls.

Built-in controls provide easy access to enterprise resources. For example, the Database control makes it easy to connect to a database and perform operations on the data using simple SQL statements, whereas the EJB control enables you to easily access an EJB. Built-in controls provide simple properties and methods for customizing their behavior, and in many cases you can add methods and callbacks to further customize the control.

A portal control is a kind of built-in Java control specific to the portal environment. If you are building a portal, you can use portal controls to expose tracking and personalization functions in multi-page portlets.

You can also build your own custom Java control from scratch. Custom Java controls are especially powerful when used to encapsulate business logic in reusable components. It can act as the nerve center of a piece of functionality, implementing the desired overall behavior and delegating subtasks to built-in Java controls (and/or other custom Java controls). This use of a custom Java control ensures

modularity and encapsulation. Web services, JSP pages, or other custom Java controls can simply use the custom Java control to obtain the desired functionality, and changes that may become necessary can be implemented in one software component instead of many.

If you are connecting to an enterprise resource that exposes a standards-based, J2EE, or Web Services interface, you can create a custom Java control to directly connect to that application. However, if you are connecting to an external resource that is proprietary or does not expose standard J2EE APIs, you may need to use a JCA (Java Connector Architecture) adaptor and an Application View control rather than a Java control to connect to that resource. JCA adaptors and the Application View control are available through WebLogic Integration.

Getting Started with Java Controls

When you're building WebLogic platform applications, Java controls provide a convenient way to incorporate access to resources and encapsulate business logic. If you've used WebLogic Workshop, you may be familiar with built-in Java controls such as the Database control, EJB control, Web Service control, and so on. These are included with the IDE, but you can also create your own custom Java control. You can use controls from within the many kinds of components that make up WebLogic platform applications. A good practice is to use the custom Java control to implement your business logic and call built-in controls when the implementation of the business logic requires this.

This topic provides an overview of Java controls in platform applications. It includes the following sections:

What Are Java Controls?

Java controls are reusable components you can use anywhere within a platform application. You can use built-in controls provided with WebLogic Workshop, or you can create your own.

Note: In previous versions, controls were represented as CTRL files. While applications built with these controls are still supported, they are deprecated for future versions. You should build new applications with Java controls based on the new model.

Uses for Java controls. The framework that supports Java controls is flexible, supporting a wide variety of uses for controls. Java controls can:

Contain business logic you want to keep separate from other application code, or which may be reused.

Provide access to resources such as databases or other resources.

Collect logic that coordinates multiple actions, such as those that involve multiple database queries, calls to Enterprise JavaBeans (with the EJB control), and so on. A control participates in the implicit transaction of a conversational container, such as a web service that is conversational.

Built-in and custom Java controls. WebLogic Workshop provides several built-in controls, and you can build your own.

WebLogic Workshop provides several built-in controls, mostly designed to provide access to resources. For example, you can use the EJB control for access to Enterprise JavaBeans, the JMS control for access to the Java Message Service, and so on. For more information about the built-in controls, see Using Built-In Java Controls.

You can build your own controls that are based on the same framework on which built-in controls are based. You design a custom control from the ground up, designing its interface and business logic, adding other controls as needed. You can design a custom control for use in one project, or you can design a custom control for easy reuse in multiple projects. For more information about the custom controls, see Building Custom Java Controls. The tutorial, Tutorial: Java Control, provides a hands-on introduction to building custom controls. Much of this topic also includes information on building your own controls.

Java Controls in the IDE

Built-in Java controls, and custom Java controls that have been set up for use in multiple projects, are listed in the WebLogic Workshop Data Palette. By default, the Data Palette is displayed in the lower-right corner of the IDE. You can add new controls to a design by clicking the Data Palette's Add menu, as shown here:

When a control is in your design, its methods and callbacks are also listed in the palette. You can also drag methods and callbacks onto your design to create "pass-through" methods. A pass-through is a shortcut way to call a control's method from your current design.

Java controls appear in Design View, but will look slightly different depending on the file type you are designing with. The following illustrations show a custom (POVerify) and built-in (EJB control) Java control in various types of component source files.

Controls in a web service (JWS) design:

Controls in a JavaServer Pages (JSP) design:

Controls in a Java page flow (JPF) action view:

Controls in a Java control (JCS) design:

Building Custom Java Controls

You can build your own Java controls. Java controls you build are like those provided with WebLogic Workshop in that they provide a way to encapsulate business logic or access a resource, and yet expose a simple interface. However, unlike controls that are built into WebLogic Workshop, where you have access to an interface that extends the source, you can use your own control source files nested within the project that accesses the control. This makes Java controls particularly useful as containers for code that should reside in the same project but which is best kept separate.

Ways to Think About Custom Controls

Local controls and control projects. You can use controls locally as source, or group them into control projects.

A control is said to be local when its source files reside in the same project as the code that uses the control. This is the simplest way to use Java controls. You can create a JCS file, add methods and callbacks to it, then call the methods from code in the same project. This is most likely the way you will use Java controls you create. For step-by-step instructions on creating and using local Java controls, see How Do I: Create and Use a Custom Java Control Within an

Existing Project? You might also be interested in Tutorial: Java Control. For examples of local controls, see the SamplesApp application installed with WebLogic Workshop; there, look in the WebServices project, in its localControls subfolder.

Control projects provide a way to group related controls, and to package them for distribution among multiple projects. You create a control project just as you would other kinds of projects, then add files for your controls. The result of a control project is a JAR file you can distribute for use in any WebLogic Workshop application. By default, building a control project will automatically copy the resulting JAR to the Libraries folder of the application containing the project. Tutorial: Java Control includes information about packaging controls into a control project. The ControlProject project in the SamplesApp application installed with WebLogic Workshop is an example of a control project. For step-by-step instructions on beginning a control project, see How Do I: Create and Use a Java Control Within a Control Project?

Regular and customizable controls. Some controls provide a static interface, some are customizable.

Most of the custom controls you build will probably be regular controls. They don't provide a customizable interface. That is, their interface is already defined when an application developer adds them to an application. In this way, a regular control is like a library of reusable code. The built-in Timer control is an example of a regular control, as are the controls whose source code is included in the SamplesApp application installed with WebLogic Workshop.

Most of the built-in controls provided with WebLogic Workshop are customizable controls. That is, when you add a new one to a project, WebLogic Workshop generates a JCX file that extends the control. In some cases, such as with the Database control or JMS control, you can customize the control by adding or editing methods defined in the JCX file. Others are customized for you, as with the EJB control, which is customized based on the EJB the control will be accessing. Building customizable custom controls is an advanced subject beyond the scope of this documentation. For an example of a customizable custom control, see the JcxCreate sample in the ControlDevKit sample application available with WebLogic Workshop.

Working with Java Control Sources

Design view for custom controls. You begin building a Java control much as you would start building other WebLogic Workshop components. After you create a Java control source (JCS) file,

Design View provides a space in which you can create a visual representation of your control's interface as well as the controls it may itself be using. The Java control design space is very much like the web service design space. The left side displays operations that will be visible to the control's clients, while the right side displays nested controls.Note: You have easy access to a control's source file when the source is in the same project as the design you're editing. When you are building a web service, page flow, or Java control that includes a

control whose source is in the same project, you can double-click the control at the right side of the design to open its JCS.

When you add a new Java control source file to a project, WebLogic Workshop also adds a JAVA file that contains the control's public interface. By default, as you work in the JCS file, adding methods, callbacks, and implementation code, WebLogic Workshop keeps the interface in sync. For example, adding an operation to the JCS will also add a corresponding method to the JAVA file. Note that the JAVA file will be kept in sync only with respect to those methods with an @common:operation annotation. This means that if you add a method to the JCS, then remove it's @common:operation annotation, WebLogic Workshop will remove the method from the JAVA file.

For step-by-step information on beginning a Custom Java control, see How Do I: Begin a New Custom Java Control. You might also be interested in How Do I: Create and Use a Custom Java Control Within an Existing Project?

Properties for Java controls. Controls you create can expose properties. For example, the Database control provides properties that specify its database connection, log category name, and so on.

You define properties by creating an annotation XML file that describes them. You then associate the file with the control source code through the JCS file's control-tags property. When a developer is using the control, setting its properties, the settings are saved as annotations in the developer's code.

For step-by-step information on defining control properties, see How Do I: Define Properties for a Java Control?

IDE characteristics for a control. You can define certain IDE characteristics for your Java control. These include the icon that represents it in palettes and menus (and whether it is displayed in the palette at all), its description in the Property Editor, and so on. You'll find settings for these characteristics in the JCS file's jc-jar property. For more information, see How Do I: Specify IDE Characteristics for a Java Control?

Testing Java controls. While you can't "run" a JCS file in Test View, as you can with the similar JWS file, WebLogic Workshop does provide a shortcut for easy testing. You can generate a JWS file through which you can exercise the control's code as you're writing it. For more information, see How Do I: Generate a JWS File to Test a Java Control?

Keep in mind that testing isn't complete until you've tried out the control in all the scenarios you expect it to support. Whether the control's container is likely to be a JWS file, a JSP file, or a JPF file, it's a good idea to build a test application that uses your control for the purpose for which you've designed it.

Invoking a Control Method

Once you've added a Java control to your application, you can invoke the methods of the Java control from Source view using the standard Java dot notation. For example, assume that you have added the CustomerDb Java control and declared a variable for the control as custDb, and that the control defines a method as follows:

String [] getAllCustomerNames()

You can invoke this method from your code as follows:

String [] custNames;

custNames = custDb.getAllCustomerNames();

Overriding Control Property Settings

Note that when you declare a control (a JCS or JCX file) within a client you can override the control's default properties.

Suppose you have a database control with the connection property defined so that the data-source-jndi-name attribute points at the data source dataSource.

DatabaseControl.jcx

/** * @jc:connection data-source-jndi-name="dataSource" */ public interface DBControl extends com.bea.control.ControlExtension, DatabaseControl

The database control is declared with its default properties in the following way.

MyWebService.jws

/** * @common:control

*/private DatabaseControl dbControl;

To override the default connection property on the database control, use the following declaration.

/** * @common:control

* @jc:connection data-source-jndi-name="myOtherDataSource" */private DatabaseControl dbControl;

In the above declaration, the database control will use myOtherDataSource instead of its default dataSource. This override value will apply to all method calls from within MyWebService.jws.

There are two important caveats when overriding control properties in this way.

(1) The property must be at the class level, not the method level. Only those properties that are scoped to the entire control class may be overriden in this way.

(2) The override occurs at the property level, not at the attribute level. It not possible to override only a single attribute on a property. You must override all of the property's attribute values. For example, suppose that the connection property had three attributes instead of just one.

DatabaseControl.jcx

/** * @jc:connection data-source-jndi-name="dataSource" attribute2="value2" attribute3="value3" */ public interface DBControl extends com.bea.control.ControlExtension, DatabaseControl

In this case, when you override the connection property, you override all of that property's attributes, not merely the data-source-jndi-name attribute. In short, the following override sets the data-source-jndi-name attribute to myOtherDataSource and attribute2 and attribute3 to null.

MyWebService.jws

/** * @common:control

* @jc:connection data-source-jndi-name="myOtherDataSource" */private DatabaseControl dbControl;

For this reason, you should specify all of the attributes when you override a control property.

/** * @common:control

* @jc:connection data-source-jndi-name="myOtherDataSource" attribute2="otherVal2" attribute3="otherVal3" */private DatabaseControl dbControl;

Handling Control Method Exceptions

The designer of a Java control may choose whether or not to explicitly declare that exceptions are thrown by the control's methods. If a control method is declared to throw exceptions, you must enclose your invocations of that method in a try-catch block.

Even if the designer of the control chooses not to declare exceptions, the support code that implements the control can still throw exceptions. The type of exception thrown is com.bea.control.ControlException.

You should strongly consider handling all control exceptions that may be thrown by the controls you use in a web service. If you do not handle the exception, the web service method will fail and the exception will be passed on to the client of your web service. In most cases, the exception is useless to the client and the client does not have the necessary information to diagnose or remedy the problem.

Control Factories: Managing Collections of Controls

This topic describes control factories, which are collections of built-in or custom Java control instances.

What Is a Control Factory?

A control factory allows a single application to manage multiple instances of the same control. For example, imagine a credit approval application that accepts batches of approval requests (one per applicant) and uses an external web service, via a Web Service control, to evaluate the requests. The application could use a control factory to create multiple instances of the Service control and dispatch requests to the Service control instances in parallel. If the control uses callbacks, a single parameterized callback handler in the calling application handles the callbacks received from all of the control instances.You can only use control factories within a Java Web Service (JWS) or Java Process Definition (JPD) file. For more information on building Java Web Services with WebLogic Workshop, see Building Web Services. For more information on using JPD files, see Guide to Building Business Processes.

Automatically Generated Factory Classes

For any control interface called MyControl, WebLogic Server generates a control factory interface

called MyControlFactory that has the following very simple shape:

interface MyControlFactory{ MyControl create();}

The implicit factory class is located in the same package as the control class; that is, if the full classname of the control interface is com.myco.mypackage.MyControl, then the full classname of the factory is com.myco.mypackage.MyControlFactory. An automatic factory class is not generated if there is a name conflict (i.e., if there is already an explicit user class called MyControlFactory.). Therefore, if you want WebLogic Workshop to automatically generate factory classes for a built-in or custom control, make sure that the name of that control does not end with the word "Factory". A control factory instance can be included in a file just as a control instance can, with the same Javadoc annotation preceding the factory declaration that would precede a single control declaration.

For example, an ordinary Web Service control is declared as follows:

/** * @common:control */ MyServiceControl oneService;

Meanwhile, a Web Service control factory is declared as follows:

/** * @common:control */ MyServiceControlFactory manyServices;

Note again that the set of annotations allowed and required on a factory are exactly the same as the set of annotations on the corresponding control. The factory behaves as if those annotations were on every instance created by the factory. Once an application includes a control factory declaration, a new instance of a single control can be created as follows:

// creates one control MyServiceControl c = manyServices.create();

// then you can just use the control, store it, or whatever. c.someMethod();

// For example, let's associate a name with the service... serviceMap.put("First Service", c);

Factory classes are automatically generated on-demand, as follows. When resolving a class named FooFactory:

1. First the class is resolved normally. For example, if there is a CLASS file or JAVA file or JCX file that contains a definition for FooFactory, then the explicitly defined class is used.

2. If there is no explicit class FooFactory, then, since the classname ends in "Factory", we remove the suffix and look for an explicit class called Foo (in the same package).

3. If Foo is found but does not implement the Control interface (i.e., is not annotated with @common:control), it's considered an error (as if Foo were never found).

4. However, if Foo is found and implements the Control interface, then the interface FooFactory is

automatically created; the interface contains only the single create() method that returns the Foo class.

All instances of the control are destroyed when the application instance that created them is destroyed.

Parameterized Callback Handlers

Since there may be multiple controls that were created with a single control factory, and they all have the same instance name, a mechanism is provided to enable you to tell which instance of the control is sending a callback.

For example, for the oneService example above, an event handler still has the following form:

void oneService_onSomeCallback(String arg) { System.out.println("arg is " + arg); }

For callback handlers that are receiving callbacks from factory-created control instances, the callback handler must take an extra first parameter that is in addition to the ordinary parameters of the callback. The first parameter is typed as the control interface, and the control instance is passed to the event handler.

The manyServices factory callback handler looks like this:

void manyServices_onSomeCallback(MyServiceControl c, String arg) { // let's retrieve the remembered name associated with the control String serviceName = (String)serviceMap.get(c);

// and print it out System.out.println("Event received from " + serviceName); }

Developing Web Applications

Enterprise web applications today can easily contains hundreds, if not thousands of pages. These pages should not only look great visually, but also offer services to customers that require the implementation of complex business logic. Managing a complex web site can be a daunting task, especially where the business logic is implemented directly in the web pages, and changing the logic requires many edits in many locations.

WebLogic Workshop provides you with the tools to manage complex web applications using JavaServer Pages (JSPs) and Page Flows.

Separation of presentation and business logic allows for modularity of business logic implementation, such that the impact of changing business logic can be minimal. Furthermore, this separation allows the application developer to concentrate on implementing the business process using Java controls and EJBs, while the web developer can focus on the presentation. Page flows provide the navigational control, allowing a web application architect to easily design the flow between the JSP pages in the web application.

Guide to Building Page Flows

WebLogic Workshop provides you with the tools to develop web applications using JavaServer Pages (JSPs) and Page Flows, separating presentation, business logic, and navigational control to manage complexity. The topics in this section discuss these concepts and provide detailed information on how to use WebLogic Workshop to develop web applications based on page flows and JSP pages.

Why Use Page Flows?

By using page flows, you can avoid making the typical mistakes that often happen during web application development, by separating presentation, business logic implementation, and navigational control. In many web applications, web developers using JSP (or any of the other dynamic web languages such as ASP or CFM) combine presentation and business logic in their web pages. As these applications grow in complexity and are subject to continual change, this practice leads to expensive, time-consuming maintenance problems, caused by:

Limited reuse of business logic Cluttered JSP source code Unintended exposure of business-logic code to team members who focus on other aspects of

web development, such as content writers and visual designers

Page flows allow you to separate the user interface code from navigational control and other business logic. User interface code can be placed where it belongs, in the JSP files. Navigational control can be implemented easily in a page flow's single controller file, which is the nerve center of your web application. A controller file is a special Java file that uses a JPF file extension. Business logic can be implemented in the page controller file, or in Java controls that you call from JPF files.

The separation of presentation and business logic offers a big advantage to development teams. For example, you can make site navigation updates in a single JPF file, instead of having to search through many JSP files and make multiple updates. In WebLogic Workshop you can as easily navigate between page flows as between individual JSP pages. This allows you to group related web pages under one page flow, and create functionally modular web components. This approach to organizing the entities that comprise web applications makes it much easier to maintain and enhance web applications by minimizing the number of files that have to be updated to implement changes, and lowers the cost of maintaining and enhancing applications.

Another advantage of page flows is that an instance of the page flow controller class is kept alive on a per-user-session basis while the user is navigating within the scope of the page flow. This instance ends when the user exits from the page flow. You can use instance member variables in page flow classes to hold user session state.

For more information about the advantages of page flows, especially in comparison to "pure Struts" applications, see Advantages of Using Page Flows.

How Does a Page Flow Work?

A page flow is a Java class, called the "controller" class, that controls the behavior of a web application through the use of specially designed annotations and methods. The directory that contains the controller class also includes the JavaServer Pages (JSPs) used in the page flow. For a JSP to be considered part of a page flow, it must reside within the page flow directory. The JSP files use special tags which help bind to data and business logic actions. The action methods in the controller file implement code that can result in site navigation, passing data, or invoking back-end business logic via controls. Significantly, the business logic in the controller class is separate from the presentation code defined in the JSP files.

The overall purpose of a page flow is to provide you with an easy-to-use framework for building dynamic, sophisticated web applications. WebLogic Workshop provides graphical and code-level tools to simplify the development cycle. While page flows give you access to advanced features of J2EE, you do not have to be a J2EE expert to quickly develop and deploy Java-based applications built on page flows. Wizards can be used to create different types of page flows, generating the Java and JSP files

that serve as a starting point for your work. Graphical tools let you draw the relationships between web components in a controller's Flow View. In Source View, syntax completion, validation, and other programmer's aids reduce the amount of work required to get your application running.

Note: WebLogic Workshop's web application functionality is built on Struts, which is an open-source framework for building web applications in a J2EE environment.

Components of the Page Flow Programming Model

Page flows implement user interface control logic, and contain:

Action Methods Form Beans Forward Objects The Tag Library

Action Methods

In the controller class, action methods are methods that are annotated with a @jpf:action tag.

/** * @jpf:action * @jpf:forward name="success" path="page_A.jsp" */ protected Forward begin() { return new Forward( "success" ); }

Action methods can perform several functions. They can (1) implement navigation decisions, (2) move data into and out of JSP pages, and (3) invoke back-end business logic via calls to controls.

Form Beans

Form Beans are Java data structures that correspond to HTML forms. When a user submits data from an HTML form, the data is stored in a Form Bean instance. Once the data is stored in a Form Bean instance, the data is available for processing by the action methods in the controller file. Form Bean instances (containing submitted data) are typically passed as parameters to action methods.

/** * @jpf:action */ protected Forward ProcessData( MyFormBean form ) {

//Submitted data is processed here...

}

Form Beans are simple Java classes contained within the controller file. They consist of some number of fields with setter and getter methods associated with those fields. Below is a Form Bean with one field, the String name, and setter and getter methods for that field. Form Bean must extend the class com.bea.wlw.netui.pageflow.FormData.

public static class MyFormBean extends FormData {

private String name;

public void setName(String name) { this.name = name; }

public String getName() { return this.name; }

Forward Objects

Forward objects are returned by action methods. They can be used to control navigation and pass data throughout the application.

The Tag Library

The tag library contains JSP tags specifically designed to work with the controller class. Tags in the library all begin with the prefixes "netui", "netui-databinding", and "netui-template". Some of these tags perform much like familiar HTML tags, while others perform function particular to page flow web applications. The most important feature of the tag library is its ability to "data bind" to data in the controller file. Data binding allows the JSP pages to both read from and write to Java code in the controller class. This is accomplished without placing any Java code on the JSP pages, greatly enhancing the separation of data presentation and data processing.

Flow, Action, and Source Views

In the WebLogic Workshop IDE, you can switch between the Flow View, Action View, and Source View to create, modify, and view page flow components. Let's start with a simple page flow to understand the basic icons you will encounter in the Flow View, and to find out how the Flow View relates to methods and object in the Source View. In the example, navigation control is forwarded from one JSP to another. You can find this example in WebLogic Workshop at:

\weblogic81\samples\workshop\SamplesApp\WebApp\navigation\simpleNavigation\

Here is the Flow View diagram that we created for this page flow in WebLogic Workshop:

All page flow controller classes have a begin action method to define what happens each time this page flow is first navigated to. For this page flow, page_A.jsp is the first page that the user will see when the page flow's URL is accessed. The begin action is shown with a blue and green circular icon:

All other actions are represented by a blue circular icon in the Flow View:

Each JSP file that resides in a page flow's directory is shown on the Flow View, and is represented by a rectangular icon with a folded upper-right corner:

An arrow from a JSP page icon to an action icon indicates that the action can be invoked from the JSP page. For example, if there is a link on the JSP that calls the action method, this is depicted in Flow View by the following arrow.

An arrow from an action to a JSP page indicates that the execution of the action will load the target JSP page into the browser. For example:

The name of each action and JSP page is shown below the icon. The name on the arrow next to the action's circular icon corresponds to the logical name of the Forward object that is returned by the action method. The Forward object's role will be clearer when we look at the source code below.

In the WebLogic Workshop IDE, use the tabs at the bottom of the main window to switch between the graphical views and source view. When a page flow is open, its graphical representation is displayed in the Flow View window. You can switch to the page flow's graphical Action View or to its code-level Source View:

The Action View allows you to focus on a smaller portion of the page flow, for instance to examine a particular action and its form bean. The Source View is where you can customize the generated code and add business logic, or call controls that implement business logic.

Let's turn to a few examples that demonstrate some of the key features of navigational control and data processing.

Navigation: a Simple Example

As shown in the Flow View diagram, the page flow class defines an action method named toPageB. This action can be invoked by a link on the JSP page page_A.jsp.

... action="toPageB">Link to page_B.jsp

A special JSP tag library named netui-tags-html.tld is referenced. WebLogic Workshop provides this tag library and several others to help you develop dynamic web applications. The tag used here is simply invoking an action (toPageB) with a hyperlink. (For more information about the page flow tag library, see Designing User Interfaces in JSPs.)

In the controller file SimpleNavigationController.jpf, the toPageB action method is defined as follows:

SimpleNavigationController.jpf

import com.bea.wlw.netui.pageflow.Forward;

...

/** * @jpf:action * @jpf:forward name="success" path="page_B.jsp" */ public Forward toPageB() { return new Forward( "success" ); }

When the link on page_A.jsp is clicked, the page flow runtime detects the action and runs the toPageB action method. This action method is coded to return a Forward object which passes the parameter "success". (Notice that this name "success" matches the name on the corresponding action arrow in Flow View.)

Look at the two @jpf annotations that appear on the lines above this action method. These annotations are enclosed in Javadoc comments. The @jpf:action tag indicates that the toPageB method is an action method. The @jpf:forward tag describes the behavior of that method.

Putting it all together, a Forward object is returned by an action method. The Forward object passes the string "success", indicating that it should behave according to the directions encoded in the annotation @jpf:forward name="success". That annotation's path attribute has the value "page_B.jsp", which causes the page flow controller to load page_B.jsp into the browser.

The following diagram summarizes the flow in the example:

To change the navigation target of this action method, simply change the value of the path attribute. For example, if you want this action method to navigate to page_C.jsp, you would make the following change to the controller file (no change to the JSP page is necessary).

/** * @jpf:action * @jpf:forward name="success" path="page_C.jsp" */ public Forward toPageB() { return new Forward( "success" ); }

As you will see in later sections, the WebLogic Workshop IDE generates this code for you when you create a new page flow or JSP file from the graphical view. This code generation and subsequent validation of your changes saves you considerable time.

Submitting Data: A Simple Example

Suppose you want to your web application to collect data from users and then process that data in some way. The following example demonstrates how to set up a data submission process using page flows. The sample code referred to in this example can be found at:

\weblogic81\samples\workshop\SamplesApp\WebApp\handlingData\simpleSubmit\

Submitting data is a two step process: (1) the data submitted from a JSP page is loaded into a Form Bean instance and (2) the Form Bean instance is passed to an action method for processing.

Form Beans are simple Java classes with fields and setter and getter methods for accessing those fields. Form Beans classes are contained within the controller file. In most cases, Form Beans are designed to accept data submitted from JSP forms. For example, if a JSP page has input elements for name, eye_color, and height, then the Form Bean will have corresponding fields for name, eye_color, and height. The following example Form Bean can be found in the controller file SimpleSubmitController.jpf. It contains one field, name, and setter and getter methods for that field.

SimpleSubmitController.jpf

public class SimpleSubmitController extends PageFlowController { ... public static class SubmitNameForm extends FormData { private String name; public void setName(String name) { this.name = name; } public String getName() { return this.name; } } }

The input elements on the JSP page are said to be "data bound" to the fields in the Form Bean. Data binding allows the the data submitted from the JSP page to be loaded into the Form Bean instance. For example, the input element on index.jsp contains a data binding expression that refers to the name field of the Form Bean: {actionForm.name}. The expression "actionForm" refers to the Form Bean SubmitNameForm, the property ".name" refers to the name field of the Form Bean. For detailed information about data binding see Using Data Binding in Page Flows.

index.jsp

Name: ....

Finally the Form Bean instance (carrying the submitted data) is passed to the action method for processing.

/** * @jpf:action * @jpf:forward name="success" path="showName.jsp" */ protected Forward SubmitName(SubmitNameForm form) { // // The data is processed here //

return new Forward("success"); }

The submitted data can be accessed by calling the getter methods on the Form Bean.

/** * @jpf:action * @jpf:forward name="success" path="showName.jsp" */ protected Forward SubmitName(SubmitNameForm form) { if( form.getName() != null )

// do something here else // do something else here

return new Forward("success"); }

By default the Form Bean instance that is passed to the action method exists only as long as the HTTP request. This is called a "request-scoped Form Bean". When the HTTP request is destroyed, the Form Bean instance, along with the user submitted data, is destroyed. As an alternative, you can use a Page Flow-scoped Form Bean, which has a longer life cycle. For details see Form Bean Scopings.

Displaying Data: A Simple Example

Suppose that once you have collected data, you want to display it back to the user. The following example shows how to use data binding to display data to the user. The sample code referred to can be found at:

\weblogic81\samples\workshop\SamplesApp\WebApp\handlingData\simpleSubmit\

Displaying data using data binding requires that (1) the data is located somewhere where it can accessed by the JSP page and (2) the JSP page uses a data binding expression to retrieve the data from that location.

Notice the syntax of data binding expression on the JSP page. (1) It is framed by curley braces, (2) it begins with a data binding context, in this case the request context, and (3) the context is followed by an attribute, in this case "name".

In the following example, an action method places data on the name attribute of the request object.

SimpleSubmitController.jpf

/** * @jpf:action * @jpf:forward name="success" path="showName.jsp" */ protected Forward SubmitName(SubmitNameForm form) { getRequest().setAttribute("name", form.getName()); return new Forward("success"); }

After the data has been located on the name attribute of the request object, it is displayed on a JSP page using a data binding expression.

showName.jsp

Here is the data you submitted:

Note that the request object has a relatively short life-cycle. When the user makes a new request, by navigating to a new JSP page or invoking another action method, the current request object is destroyed along with the data it contains. If your application requires the data to be more persistent,

then you could use a different data binding context, for example the session object or a Page Flow-scoped Form Bean, which both have longer life-cycles. For detailed information about the different data binding contexts available, see Using Data Binding in Page Flows.

Advantages of Using Page Flows

This topic outlines the advantages of using page flows in your web applications. You may be familiar already with the Struts framework, which is a part of the Jakarta Project by the Apache Software Foundation™. Struts is an open-source framework for building Web applications based on the model-view-controller (MVC) design paradigm. WebLogic Workshop page flows extend the Struts framework to provide a simplified development model with numerous additional features:

Ease of use

Typically, native Struts development requires management and synchronization of multiple files for each Action, form bean, and the Struts configuration file. Even in the presence of tools that help edit these files, developers are still exposed to all the underlying plumbing, objects, and configuration details. Page flows provide a dramatically simpler, single-file programming model that allows you to focus on the code you care about, see a visual representation of the overall application flow, and easily navigate between pages, actions, and form beans. Page flows also provide a number of wizards to automate common tasks and visualize tag libraries. Furthermore, page flows provide key programming model benefits like thread safety. As a developer, this means that you can be insulated from some of the complexities that are pervasive in other web development models today like Struts and servlets. The result is that page flows enable you to become immediately productive in building sophisticated web applications, without the learning curve typically associated with Struts.

Nested page flows

Struts provides a useful framework for smaller applications, but has trouble scaling to larger applications. Every page and action is referenced from a single configuration file, and the manageability of applications and projects quickly degrades as the size of the application increases. But with the nesting feature of page flows, you can easily create smaller nested applications that are linked together, helping to enforce a modular design paradigm and supporting larger team development projects. Importantly, nested page flows automatically manage session state as a user moves between them, ensuring that the minimum possible level of system resources is used.

State management

Page flows make state management easy. You can put data in session state simply by using a variable in your JPF controller class, unlike with Struts action classes. Or you can easily pass data (as Java beans) to individual pages. Data stored in the session state is automatically freed as a user leaves the page flow for efficient use of session data.

Rich Data binding features

The WebLogic Workshop data binding tags and wizards make it easy to create rich, dynamic pages within a page flow. These features enable binding of user interface (UI) components to numerous data contexts (not just limited to form beans) and the data may come from any source: a database, a web service, an EJB, a custom application, and so on. In the IDE, you can drag-and-drop the data binding tags to your JSP page and bind to data, including complex types such as method invocations, repeating data, and grids. For more information, see Using Data Binding in Page Flows and Presenting Complex Data Sets in JSPs.

Service-oriented design with Java controls

Page flows have full support for Java controls, a simple programming model abstraction for accessing enterprise resources and packaging business logic. Java controls give developers access to the powerful features of the J2EE platform (security, transactions, asynchrony) in a simple, graphical environment with methods, events and properties, and enable developers to build Web applications conforming to best practices for service-oriented architecture. For more information, see Tutorial: Java Control.

Integration with Portal

Have a page flow? You can easily also have a portlet! Page flow applications can be instantly turned into portlets via a wizard in WebLogic Workshop. For more information, see How Do I: Create a Portlet? and How Do I: Add Portal Functionality to an Existing Page Flow Application?

Strong data typing

Struts treats all data as a String, making it difficult to work with rich form data. Page Flows, on the other hand, allow developers much easier access to strongly-typed data, making it a lot easier to work with form information.

Powerful exception handling

You can handle exceptions by pointing to local actions in your page flows, Page Flows, and handle not-logged-in errors globally across a set of page flows. This makes it much easier to manage errors and centralized login processes for your entire application versus managing a cloud of exception handler classes in Struts. WebLogic Workshop provides a number of exception types that represent common exception scenarios for page flow applications, such as ActionNotFoundException, LoginExpiredException, and UnfulfilledRolesException. For more information, see Handling Exceptions in Page Flows.

Iterative development experience

With the WebLogic Workshop IDE and page flows, you do not need to go through the tedious development cycle of edit, build, deploy, and test. Simply make a change in the IDE and click the Run button. The WebLogic Workshop model for automated deployment and integrated testing displays the results of your code change immediately. Plus, more errors are caught up-front through the WebLogic Workshop page flow compiler, instead of discovering the errors at runtime through exceptions or unintended behavior.

Built on the open-source Struts framework

While page flows provide a number of compelling advantages relative to Struts, keep in mind that page flows are based on Struts. This means that page flows can interoperate with existing Struts applications. You can always use the Struts Merge feature of page flows to obtain full access to underlying Struts artifacts and their configuration details. And page flows can interoperate with existing Struts applications, with both residing in the same web project. Also, with the page flow portability kit, you can run a page flow application on Apache Tomcat™ and any J2EE-compliant Servlet/JSP 2.3 container.

Designing Asynchronous Interfaces

Interactions between software components can be synchronous or asynchronous. An interaction is synchronous if the caller of a method must wait for the method's work to complete before the caller can continue its processing. An interaction is asynchronous if the called method returns immediately, allowing the caller to continue its processing without delay.An asynchronous interaction typically initiates a computation but does not wait for the result to be available, which means it must provide some way for the caller to obtain the results of the computation at a later time.

The distributed nature of web applications introduces unpredictable and sometimes very long latencies, which means it may take an operation a long time to complete. If a business process executing over the network involves human interaction at the back end, an operation can take on the order of days. If all interactions over the web were synchronous, clients with pending operations could consume resources on their host systems for unacceptably long periods of time.

WebLogic Workshop provides tools that make it easy for you to build asynchronous web services and Java controls that don't require clients to block execution while waiting for results. WebLogic Workshop provides multiple approaches for returning results to your web services' and Java controls' clients; you can choose the one that best suits each situation.

Getting Started: Using Asynchrony to Enable Long-Running Operations

WebLogic Workshop provides tools that make it easy for you to build asynchronous web services and asynchronous Java controls. This section introduces the concept of a callback, which is one of the critical design components when building an asynchronous web service or Java control, and describes the requirements for using callbacks. In addition, this section describes how to add buffering to methods and callbacks to enable the handling of high-volume traffic.

Introduction to Asynchronous Java Controls

Before reading this topic, you should understand the general concepts related to asynchronous interfaces. To learn about asynchronous interfaces, see Introduction to Asynchronous Interfaces.

In WebLogic Workshop, Java controls can have the same asynchronous behavior as web services. However, the behavior of a Java control is dependent on the nature of the Java control's client.

To understand this concept, think about how Java controls are used by their clients: the client is a web service, a page flow or another Java control and the Java control instance is declared as a member variable of the client. This means that the Java control instance cannot have a lifetime that exceeds that of its client.

Using Java Controls from Web Services

WebLogic Workshop web services can be conversational. Conversations allow you to control the lifetime of an instance of a web service. Since the lifetime of member variables of a web service is the same as the lifetime of the instance of the web service, Java controls references by a web service also have the same lifetime. Therefore, if a Java control's client is a web service the Java control may freely use callbacks to communicate with its client because the client is guaranteed to exist if the Java control instance exists. Note that the Java control's client must still explicitly implement handlers for each Java control callback it wishes to receive. To learn more about conversations and WebLogic Workshop web services, see Designing Conversational Web Services.

Using Java Controls from Page Flows

A page flow may also declare a Java control member variable. However, page flows ultimately represent web pages, and web pages operate on a strictly request-response basis from the user's browser. There is no way to "push" information to the browser with a browser-originated request initiated by or on behalf of the user. Since data cannot be "pushed" to the browser, it doesn't make sense to "push" data to a page flow, which is what a callback would represent. Therefore, page flows are not capable of receiving callbacks from a Java control.

However, it is possible to use an intermediary Java control with a polling interface to provide an "adapter" between a page flow and a Java control that uses callbacks. See Example 2, below, but substitute page flow for the non-conversational web service in the example.

With page flows, the limiting issue is not conversational lifetime as it is for web services. The limiting issue with page flows is the inability to "push" information out to the browser. The scenario in Example 2 below hides the "push" (the callback) in Java control A, which presents only a "pull" interface to its client. To learn more about polling interfaces, see Using Polling as an Alternative to Callbacks.

Using Java Controls from Other Java Controls

Whether callbacks can be sent form one Java control to another depends on the ultimate client at the end of the chain of Java controls. This is probably best illustrated by examples:

Example 1

Assume that you have a conversational web service that uses Java control A, which in turn uses Java control B. The lifetime of the Java control A instance is the same as the lifetime as the web service's conversation, and the lifetime of the Java control B instance is the same as that of Java control A (everything has the same lifetime: that of the web service's conversation). In this situation Java control B may use callbacks to communicate with Java control A, and Java control A may use callbacks to communicate with the web service.

Example 2

Assume the same situation as Example 1, but with a non-conversational web service. Since the web service is non-conversational, the lifetime of an instance of the web service spans only a single invocation of any of the web service's methods. Therefore the lifetime of the web services member variables, including its instance of Java control A, is the same, and the lifetime of the member variables of Java control A, including Java control B, is also the same. Java control A cannot use callbacks to the web service because once the web service method completes Java control A no longer exists. However, if Java control A were to provide a polling interface to be used by the web service, then Java control B may use callbacks to communicate with Java control A. Here is a scenario:

1. A web service client calls a web service method and an instance of the web service is created. 2. An instance of Java control A is created because it is a member variable of the web service. 3. An instance of Java control B is created because it is a member variable of Java control A. 4. The web service method calls the "start request" method of a polling interface provided by

Java control A. 5. The "start request" method of Java control A calls a "start request" method of Java control B

that will eventually result in a callback to Java control A. 6. The web service method repeatedly calls a "check status" method of Java control A. The

method returns false until the result is available. 7. When Java control B's work is completed, it calls a callback of Java control A. 8. The callback handler of Java control A stores the result. 9. The next time the web service calls the "check status" method of Java control A, it returns true. 10. The web service calls a "get result" method on Java control A. 11. The web service returns the result as the return value of the method invoked in step 1. 12. The web service instance is released, causing the release of the instance of Java control A and

in turn the release of the instance of Java control B.

Note that step 6 is not advisable if Java control B's work will take a long time. The initial request to the web service in step 1 may time out.

Designing Conversational Web Services

A single web service may communicate with multiple clients at the same time, and it may communicate with each client multiple times. In order for the web service to track data for the client during asynchronous communication, it must have a way to remember which data belongs to which client and to keep track of where each client is in the process of operations. In WebLogic Workshop,

you use conversations to uniquely identify a given communication between a client and your web service and to maintain state between operations.

Conversations are essential for any web service involved in asynchronous communication. This includes web services that communicate with clients using callbacks or polling interfaces, and web services that use controls with callbacks.

Best Practices for Designing Asynchronous Interfaces

This section discusses the best practices for creating and using web services and Java controls with asynchronous interfaces. The first topic describes how to use polling as an alternative to callbacks. Then, various design principles are recommended for designing web services and Java controls that can be called by both other web services and JSP (web) pages.

Designing Robust Asynchronous Interfaces

The preceding sections have presented various design options that can be included when building web services and Java controls. Given these options, what exactly constitutes a good design and creates a successful and robust web service or Java control? This topic explores several typical design solutions.

Do I Need an Asynchronous Interface?

The first question you might need to answer for a web service or Java control is whether the service or control needs to be asynchronous. There are certainly cases where a non-conversational, synchronous service or control will suffice, especially when the functionality it implements is relatively small, the request handling is relatively short, and the underlying infrastructure supporting this web service is solid, for instance if you are working on a fail-proof intranet or if your control is called by a (synchronous) web service on the same server. However, if any of these factors are not true or uncertain at the time of design, you will want to make your service or control asynchronous.

Do I Need to Use Callbacks?

Callbacks are a powerful approach to designing asynchronous web services or Java controls, relieving the client from periodically checking a request's status, as is required with polling. Especially when it is unclear how long a request will take to process, or if processing times vary wildly, using a callback is likely the most elegant implementation of asynchrony and loose coupling. Using callbacks in combination with buffering of both methods and callbacks is particularly effective in dealing with high-volume traffic. However, callbacks require that the client is designed to accept incoming messages and is hosted in an environment that supports message delivery.

Do I Need to Use Polling?

All asynchronous web services and Java controls should provide a polling interface. If the web service or Java control is asynchronous, a polling interface is required by any client that cannot accept callbacks; a polling interface is the only way such a client can obtain the results of operations initiated by asynchronous method invocations. You should think of a polling interface as the foundation interface of a web service or Java control, and callbacks as "extra" functionality that is convenient for clients who can handle callbacks.

The exception to this guideline is a Java control for which the only clients will be conversational web services or Java controls invoked by conversational web services. Conversational WebLogic Workshop web services can always accept callbacks. However, Java controls should be designed to be reusable. Assuming that the only clients a Java control will ever have are WebLogic Workshop web services limits the reusability of the Java control.

A Robust Web Service or Java Control

To create an asynchronous web service or Java control that is robust and handles all situations, it is recommended that you implement both a callback and a polling interface. Your design might (among others) include the following methods:

A start_request_asynch buffered method that the client will call to initiate a request. The method starts a conversation and notes that the callback mechanism will be used when the results are ready.

A callback_results buffered callback that sends the results to the client when the request is completed and finishes the conversation.

A start_request_synch buffered method that the client will call to initiate a request. The method starts a conversation and notes that the polling mechanism will be used when the results are ready.

A check_status unbuffered method that the client will periodically call to check the status of the request. The method continues a conversation and returns a Boolean value indicating whether or not the request has been completely handled.

A get_results unbuffered method that the client will call to get the results of the request. The method finishes the conversation.

Handling XML with XMLBeans

XMLBeans provides a simple, easy-to-use means for accessing XML. With XMLBeans, you can compile schema to generate Java types that can be bound to XML based on the schema. You can also access XML with schema by using an XML cursor, which provides an access model that is an alternative to DOM-based models.

Getting Started with XMLBeans

XMLBeans provides intuitive ways to handle XML that make it easier for you to access and manipulate XML data and documents in Java.

Characteristics of XMLBeans approach to XML:

It provides a familiar Java object-based view of XML data without losing access to the original, native XML structure.

The XML's integrity as a document is not lost with XMLBeans. XML-oriented APIs commonly take the XML apart in order to bind to its parts. With XMLBeans, the entire XML instance document is handled as a whole. The XML data is stored in memory as XML. This means that the document order is preserved as well as the original element content with whitespace.

With types generated from schema, access to XML instances is through JavaBean-like accessors, with get and set methods.

It is designed with XML schema in mind from the beginning — XMLBeans supports all XML schema definitions.

Access to XML is fast.

The starting point for XMLBeans is XML schema. A schema (contained in an XSD file) is an XML document that defines a set of rules to which other XML documents must conform. The XML Schema specification provides a rich data model that allows you to express sophisticated structure and constraints on your data. For example, an XML schema can enforce control over how data is ordered in a document, or constraints on particular values (for example, a birth date that must be later than 1900). Unfortunately, the ability to enforce rules like this is typically not available in Java without writing custom code. XMLBeans honors schema constraints.

Note: Where an XML schema defines rules for an XML document, an XML instance is an XML document that conforms to the schema.

You compile a schema (XSD) file to generate a set of Java interfaces that mirror the schema. With these types, you process XML instance documents that conform to the schema. You bind an XML instance document to these types; changes made through the Java interface change the underlying XML representation.

Previous options for handling XML include using XML programming interfaces (such as DOM or SAX) or an XML marshalling/binding tool (such as JAXB). Because it lacks strong schema-oriented typing, navigation in a DOM-oriented model is more tedious and requires an understanding of the complete object model. JAXB provides support for the XML schema specification, but handles only a subset of it; XMLBeans supports all of it. Also, by storing the data in memory as XML, XMLBeans is able to reduce the overhead of marshalling and demarshalling.

Accessing XML Using Its Schema

To get a glimpse of the kinds of things you can do with XMLBeans, take a look at an example using XML for a purchase order. The purchase order XML contains data exchanged by two parties, such as two companies. Both parties need to be able to rely on a consistent message shape, and a schema specifies the common ground.

Here's what a purchase order XML instance might look like.

Gladys Kravitz Anytown, PA 2003-01-07T14:16:00-05:00 Burnham's Celestial Handbook, Vol 1 5 21.79 2 Burnham's Celestial Handbook, Vol 2 5 19.89 2

ZipShip 0.74

This XML includes a root element, purchase-order, that has four kinds of child elements: customer, date, line-item, and shipper. An intuitive, object-based view of this XML would provide an object representing the purchase-order element, and it would have methods for getting the date and for getting subordinate objects for customer, line-item, and shipper elements. Each of the last three would have its own methods for getting the data inside them as well.

Looking at the Schema

The following XML is the the schema for the preceding purchase order XML. It defines the XML's "shape" — what its elements are, what order they appear in, which are children of which, and so on.

<xs:schema targetNamespace="http://openuri.org/easypo" xmlns:po="http://openuri.org/easypo"

xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">

<xs:element name="purchase-order"> <xs:complexType> <xs:sequence> <xs:element name="customer" type="po:customer"/> <xs:element name="date" type="xs:dateTime"/> <xs:element name="line-item" type="po:line-item" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="shipper" type="po:shipper" minOccurs="0"/> </xs:sequence> </xs:complexType> </xs:element> <xs:complexType name="customer"> <xs:sequence> <xs:element name="name" type="xs:string"/> <xs:element name="address" type="xs:string"/> </xs:sequence> </xs:complexType> <xs:complexType name="line-item"> <xs:sequence> <xs:element name="description" type="xs:string"/> <xs:element name="per-unit-ounces" type="xs:decimal"/> <xs:element name="price" type="xs:double"/> <xs:element name="quantity" type="xs:int"/> </xs:sequence> </xs:complexType> <xs:complexType name="shipper"> <xs:sequence> <xs:element name="name" type="xs:string"/> <xs:element name="per-ounce-rate" type="xs:decimal"/> </xs:sequence> </xs:complexType></xs:schema>This schema describes the purchase order XML instance by defining the following:

Definitions for three complex types — customer, line-item, and shipper. These are the types used for the children of the purchase-order element. In schema, a complex type is one that defines an element that may have child elements and attributes. The sequence element nested in the complex type lists its child elements.

These are also global types. They are global because they are at the top level of the schema (in other words, just beneath the schema root element). This means that they may be referenced from anywhere else in the schema.

Use of simple types within the complex types. The name, address, and description elements (among others) are typed as simple types. As it happens, these are also built-in types. A built-in type (here, one with the "xs" prefix) is part of the schema specification. (The specification defines 46 built-in types.)

A global element called purchase-order. This element definition includes a nested complex type definition that specifies the child elements for a purchase-order element. Notice that the complex type includes references to the other complex types defined in this schema.

In other words, the schema defines types for the child elements and describes their position as subordinate to the root element, purchase-order.

When you use the XMLBean compiler with an XSD file such as this one, you generate a JAR file containing the interfaces generated from the schema.

Writing Java Code That Uses the Interfaces

With the XMLBeans interfaces in your application, you can write code that uses the new types to handle XML based on the schema. Here's an example that extracts information about each of the ordered items in the purchase order XML, counts the items, and calculates a total of their prices. In particular, look at the use of types generated from the schema and imported as part of the org.openuri.easypo package.

The printItems method receives a File object containing the purchase order XML file.

package docs.xmlbeans;

import java.io.File;import com.bea.xml.*;import org.openuri.easypo.PurchaseOrderDocument;import org.openuri.easypo.PurchaseOrder;import org.openuri.easypo.LineItem;

public class POHandler { public static void printItems(File po) throws Exception { /* * All XMLBeans schema types provide a nested Factory class you can * use to bind XML to the type, or to create new instances of the type. * Note that a "Document" type such as this one is an XMLBeans * construct for representing a global element. It provides a way * for you to get and set the contents of the entire element. * * Also, note that the parse method will only succeed if the * XML you're parsing appears to conform to the schema. */ PurchaseOrderDocument poDoc = PurchaseOrderDocument.Factory.parse(po);

/* * The PurchaseOrder type represents the purchase-order element's * complex type. */ PurchaseOrder po = poDoc.getPurchaseOrder();

/* * When an element may occur more than once as a child element, * the schema compiler will generate methods that refer to an * array of that element. The line-item element is defined with * a maxOccurs attribute value of "unbounded", meaning that * it may occur as many times in an instance document as needed. * So there are methods such as getLineItemArray and setLineItemArray. */ LineItem[] lineitems = po.getLineItemArray(); System.out.println("Purchase order has " + lineitems.length + " line items.");

double totalAmount = 0.0; int numberOfItems = 0;

/* * Loop through the line-item elements, using generated accessors to * get values for child elements such a description, quantity, and * price. */

for (int j = 0; j < lineitems.length; j++) { System.out.println(" Line item: " + j); System.out.println( " Description: " + lineitems[j].getDescription()); System.out.println(" Quantity: " + lineitems[j].getQuantity()); System.out.println(" Price: " + lineitems[j].getPrice()); numberOfItems += lineitems[j].getQuantity(); totalAmount += lineitems[j].getPrice() * lineitems[j].getQuantity(); } System.out.println("Total items: " + numberOfItems); System.out.println("Total amount: " + totalAmount); }}

Notice that types generated from the schema reflect what's in the XML:

A PurchaseOrderDocument represents the global root element. A getPurchaseOrder method returns a PurchaseOrderDocument.PurchaseOrder type that

contains child elements, including line-item. A getLineItemArray method returns a LineItem array containing the line-item elements.

Other methods, such as getQuantity, getPrice, and so on, follow naturally from what the schema describes, returning corresponding children of the line-item element.

The name of the package containing these types is derived from the schema's target namespace.

Capitalization and punctuation for generated type names follow Java convention. Also, while this example parses the XML from a file, other parse methods support a Java InputStream object, a Reader object, and so on.

The preceding Java code prints the following to the console:

Purchase order has 3 line items. Line item 0 Description: Burnham's Celestial Handbook, Vol 1 Quantity: 2 Price: 21.79 Line item 1 Description: Burnham's Celestial Handbook, Vol 2 Quantity: 2 Price: 19.89Total items: 4Total amount: 41.68

Creating New XML Instances from Schema

As you've seen XMLBeans provides a "factory" class you can use to create new instances. The following example creates a new purchase-order element and adds a customer child element. It then inserts name and address child elements, creating the elements and setting their values with a single call to their set methods.

public PurchaseOrderDocument createPO(){ PurchaseOrderDocument newPODoc = PurchaseOrderDocument.Factory.newInstance(); PurchaseOrder newPO = newPODoc.addNewPurchaseOrder(); Customer newCustomer = newPO.addNewCustomer(); newCustomer.setName("Doris Kravitz"); newCustomer.setAddress("Bellflower, CA");

return newPODoc;}

The following is the XML that results. Note that XMLBeans assigns the correct namespace based on the schema, using an "ns1" (or, "namespace 1") prefix. For practical purposes, the prefix itself doesn't really matter — it's the namespace URI (http://openuri.org/easypo) that defines the namespace. The prefix is merely a marker that represents it.

Doris Kravitz Bellflower, CA

Note that all types (including those generated from schema) inherit from XmlObject, and so provide a Factory class. For an overview of the type system in which XmlObject fits, see XMLBeans Support for Built-In Schema Types. For reference information, see XmlObject Interface.

XMLBeans Hierarchy

The generated types you saw used in the preceding example are actually part of a hierarchy of XMLBeans types. This hierarchy is one of the ways in which XMLBeans presents an intuitive view of schema. At the top of the hierarchy is XmlObject, the base interface for XMLBeans types. Beneath this level, there are two main type categories: generated types that represent user-derived schema types, and included types that represent built-in schema types.

This topic has already introduced generated types. For more information, see Java Types Generated from User-Derived Schema Types.

Built-In Type Support

In addition to types generated from a given schema, XMLBeans provides 46 Java types that mirror the 46 built-in types defined by the XML schema specification. Where schema defines xs:string, xs:decimal, and xs:int, for example, XMLBeans provides XmlString, XmlDecimal, and XmlInt. Each of these also inherits from XmlObject, which corresponds to the built-in schema type xs:anyType.

XMLBeans provides a way for you to handle XML data as these built-in types. Where your schema includes an element whose type is, for example, xs:int, XMLBeans will provide a generated method designed to return an XmlInt. In addition, as you saw in the preceding example, for most types there will also be a method that returns a natural Java type such as int. The following two lines of code return the quantity element's value, but return it as different types.

// Methods that return simple types begin with an "x".XmlInt xmlQuantity = lineitems[j].xgetQuantity();// Methods that return a natural Java type are unadorned.int javaQuantity = lineitems[j].getQuantity();

In a sense both get methods navigate to the quantity element; the getQuantity method goes a step further and converts the elements value to the most appropriate natural Java type before returning it. (XMLBeans also provides a means for validating the XML as you work with it.)

If you know a bit about XML schema, XMLBeans types should seem fairly intuitive. If you don't, you'll learn a lot by experimenting with XMLBeans using your own schemas and XML instances based on them.

For more information on the methods of types generated from schema, see Methods for Types Generated From Schema. For more about the how XMLBeans represents built-in schema types, see XMLBeans Support for Built-In Schema Types.

Using XQuery Expressions

With XMLBeans you can use XQuery to query XML for specific pieces of data. XQuery is sometimes referred to as "SQL for XML" because it provides a mechanism to access data directly from XML documents, much as SQL provides a mechanism for accessing data in traditional databases.

XQuery borrows some of its syntax from XPath, a syntax for specifying nested data in XML. The following example returns all of the line-item elements whose price child elements have values less than or equal to 20.00:

PurchaseOrderDocument doc = PurchaseOrderDocument.Factory.parse(po);

/* * The XQuery expression is the following two strings combined. They're * declared separately here for convenience. The first string declares * the namespace prefix that's used in the query expression; the second * declares the expression itself. */String nsText = "declare namespace po = 'http://openuri.org/easypo'";String pathText = "$this/po:purchase-order/po:line-item[po:price <= 20.00]";String queryText = nsText + pathText;

XmlCursor itemCursor = doc.newCursor().execQuery(queryText);System.out.println(itemCursor.xmlText());

This code creates a new cursor at the start of the document. From there, it uses the XmlCursor interface's execQuery method to execute the query expression. In this example, the method's parameter is an XQuery expression that simply says, "From my current location, navigate through the purchase-order element and retrieve those line-item elements whose value is less than or equal to 20.00." The $this variable means "the current position." For more information about XQuery, see XQuery 1.0: An XML Query Language at the W3C web site.

Using XML Cursors

In the preceding example you may have noticed the XmlCursor interface. In addition to providing a way to execute XQuery expression, an XML cursors offers a fine-grained model for manipulating data. The XML cursor API, analogous to the DOM's object API, is simply a way to point at a particular piece of data. So, just like a cursor helps navigate through a word processing document, the XML cursor defines a location in XML where you can perform actions on the selected XML.

Cursors are ideal for moving through an XML document when there's no schema available. Once you've got the cursor at the location you're interested in, you can perform a variety of operations with it. For example, you can set and get values, insert and remove fragments of XML, copy fragments of XML to other parts of the document, and make other fine-grained changes to the XML document.

The following example uses an XML cursor to navigate to the customer element's name child element.

PurchaseOrderDocument doc = PurchaseOrderDocument.Factory.parse(po);

XmlCursor cursor = doc.newCursor();cursor.toFirstContentToken();cursor.toFirstChildElement();cursor.toFirstChildElement();System.out.println(cursor.getText());

cursor.dispose();

What's happening here? As with the earlier example, the code loads the XML from a File object. After loading the document, the code creates a cursor at its beginning. Moving the cursor a few times takes it to the nested name element. Once there, the getText method retrieves the element's value.

This is just an introduction to XML cursors. For more information about using cursors, see Navigating XML with Cursors.

Where to Go Next

XMLBeans provides intuitive ways to handle XML, particularly if you're starting with schema. If you're accessing XML that's based on a schema, you'll probably find it most efficient to access the XML through generated types specific to the schema. To do this, you begin by compiling the schema to generate interfaces. For more information on using XMLBeans types generated by compiling schema, see Java Types Generated From User-Derived Schema Types and Methods for Types Generated From Schema.

You might be interested in reading more about the type system on which XMLBeans is based, particularly if you're using types generated from schema. XMLBeans provides a hierarchical system of types that mirror what you find in the XML schema specification itself. If you're working with schema, you might find it helps to understand how these types work. For more information, see XMLBeans Support for Built-In Schema Types and Introduction to Schema Type Signatures.

XMLBeans provides access to XML through XQuery, which borrows path syntax from XPath. With XQuery, you can specify specific fragments of XML data with or without schema. To learn more about using XQuery and XPath in XMLBeans, see Selecting XML with XQuery and XPath.

You can use the XmlCursor interface for fine-grained navigation and manipulation of XML. For more information, see Navigating XML with Cursors.

Selecting XML with XQuery and XPath

You can use XQuery and XPath to retrieve specific pieces of XML as you might retrieve data from a database. XQuery and XPath provide a syntax for specifying which elements and attributes you're interested in. The XMLBeans API provides two methods for executing XQuery and XPath expressions, and two differing ways to use them. The methods are selectPath and execQuery, and you can call them from XmlObject (or an object inheriting from it) or XmlCursor. The results for the methods differ somewhat.

Using the selectPath Method

The selectPath method is the most efficient way to execute XPath expressions. The selectPath method is optimized for XPath. When you use XPath with the selectPath method, the value returned is an array of values from the current document. In contrast, when you use execQuery, the value returned is a new document.

Calling from XmlObject

When called from XmlObject (or a type that inherits from it), this method returns an array of objects. If the expression is executed against types generated from schema, then the type for the returned array is one of the Java types corresponding to the schema.

For example, imagine you have the following XML containing employee information. You've compiled the schema describing this XML and the types generated from schema are available to your code.

Fred Jones 900 Aurora Ave.

Seattle WA 98115 2011 152nd Avenue NE Redmond WA 98052 (425)555-5665 (206)555-5555 (206)555-4321 If you wanted to find the phone numbers whose area code was 206, you could capture the XPath expression in this way:

String queryExpression = "declare namespace xq='http://openuri.org/selectPath'" + "$this/xq:employees/xq:employee/xq:phone[contains(., '(206)')]"

Notice in the query expression that the variable $this represents the current context node (the XmlObject that you are querying from). In this example you are querying from the document level XmlObject.

You could then print the results with code such as the following:

/* * Retrieve the matching phone elements and assign the results to the corresponding * generated type. */PhoneType[] phones = (PhoneType[])empDoc.selectPath(queryExpression);/* * Loop through the results, printing the value of the phone element. */for (int i = 0; i < phones.length; i++){ System.out.println(phones[i].stringValue());}

Calling from XmlCursor

When called from an XmlCursor instance, the selectPath method retrieves a list of selections, or locations in the XML. The selections are remembered by the cursor instance. You can use methods such as toNextSelection to navigate among them.

The selectPath method takes an XPath expression. If the expression returns any results, each of those results is added as a selection to the cursor's list of selections. You can move through these selections in the way you might use java.util.Iterator methods to move through a collection.

For example, for a path such as $this/employees/employee, the results would include a selection for each employee element found by the expression. Note that the variable $this is always bound to the current context node, which in this example is the document. After calling the selectPath method, you would use various "selection"-related methods to work with the results. These methods include:

getSelectionCount() to retrieve the number of selections resulting from the query. toNextSelection() to move the cursor to the next selection in the list (such as to the one

pointing at the next employee element found).

toSelection(int) to move the cursor to the selection at the specified index (such as to the third employee element in the selection).

hasNextSelection() to find out if there are more selections after the cursor's current position. clearSelections() clears the selections from the current cursor. This doesn't modify the

document (in other words, it doesn't delete the selected XML); it merely clears the selection list so that the cursor is no longer keeping track of those positions.

The following example shows how you might use selectPath, in combination with the push and pop methods, to maneuver through XML, retrieving specific values. public void printZipsAndWorkPhones(XmlObject xml){ // Declare the namespace that will be used. String xqNamespace = "declare namespace xq='http://openuri.org/selectPath'";

// Insert a cursor and move it to the first element. XmlCursor cursor = xml.newCursor(); cursor.toFirstChild(); /* * Save the cursor's current location by pushing it * onto a stack of saved locations. */ cursor.push(); // Query for zip elements. cursor.selectPath(xqNamespace + "$this//xq:zip"); /* * Loop through the list of selections, getting the value of * each element. */ while (cursor.toNextSelection()) { System.out.println(cursor.getTextValue()); } // Pop the saved location off the stack. cursor.pop(); // Query again from the top, this time for work phone numbers. cursor.selectPath(xqNamespace + "$this//xq:phone[@location='work']"); /* * Move the cursor to the first selection, them print that element's * value. */ cursor.toNextSelection(); System.out.println(cursor.getTextValue()); // Dispose of the cursor. cursor.dispose();}

Using selections is somewhat like tracking the locations of multiple cursors with a single cursor. This becomes especially clear when you remove the XML associated with a selection. When you do so the selection itself remains at the location where the removed XML was, but now the selection's location is immediately before the XML that was after the XML you removed. In other words, removing XML created a kind of vacuum that was filled by the XML after it, which shifted up into the space — up into position immediately after the selection location. This is exactly the same as if the selection had been another cursor.

Finally, when using selections keep in mind that the list of selections is in a sense "live". The cursor you're working with is keeping track of the selections in the list. In other words, be sure to call the clearSelections method when you're finished with the selections, just as you should call the XmlCursor.dispose() method when you're finished using the cursor.

Using the execQuery Method

Use the execQuery method to execute XQuery expressions that are more sophisticated than paths. These expressions include more sophisticated loops and FLWR (For, Let, Where, and Results) expressions.

Note: Be sure to see the simpleExpressions sample in the SamplesApp application for a sampling of XQuery expressions in use.

Calling from XmlObject

Unlike selectPath, calling execQuery from an XmlObject instance will return an XmlObject array. If the XmlObject instances resulting from the XQuery match a recognized XMLBeans type (the namespace and top level element name match up with an XMLBeans type) then the XmlObject will be typed; otherwise the XmlObject will be untyped.

Calling from XmlCursorCalling execQuery from an XmlCursor instance returns a new XmlCursor instance. The cursor returned is positioned at the beginning of a new xml document representing the query results, and you can use it to move through the results, cursor-style (for more information, see Navigating XML with Cursors). If the document resulting from the query execution represents a recognized XMLBeans type (the namespace and top level element name match up with an XMLBeans type) then the document resulting from the xquery will have that Java type; otherwise the resulting document will be untyped.

Building Integration Applications

The integrated development environment in WebLogic Workshop includes a framework and tools for building WebLogic Integration applications. The topics in this section provide information about designing business processes that span applications, users, enterprise networks, and trading partners.

Tutorial: Building Your First Business Process

Provides a tour of the features available to design business processes for a WebLogic Workshop application by describing how to create a process that orchestrates the processing of a request for quote. Includes designing asynchronous communication with Web Service controls and Process controls, designing decision nodes, looping logic, parallel nodes, data transformations, Message Broker publish and subscription logic, and so on.

Tutorial: Building Your First Data Transformation

Introduces the basics of building a data transformation by describing how to create and test an XML-to-XML data transformation.

Guide to Building Business Processes

Describes how to build and test business processes using graphical tools. This topic includes how to design your business process logic, including designing looping constructs, decision nodes, switch nodes, interactions with clients and external resources, transactions, stateful and stateless processes, versioning business processes, and so on.

Guide to Data Transformation

Describes how to use the mapper functionality to create a data transformation graphically and how to import an existing eXtensible Stylesheet Language Transformation (XSLT) into WebLogic Workshop for data transformation.

Using Integration Controls

Describes how to use controls that make it easy to access enterprise resources, such as databases, file systems, Enterprise Java Beans, the Worklist, RosettaNet, ebXML, Trading Partner Management systems, and so on from within your application.

How Do I ...?

Provides step-by-step instructions for common tasks needed to build business processes, including creating new applications and business processes, and importing Schemas and Message Broker channel files. This topic also includes descriptions of the keyboard shortcuts and productivity accelerators you can use while building your business processes.

Java Class Reference

Provides reference information for WebLogic Integration API Javadoc for WebLogic Integration controls, business processes (JPDs), data transformation, Worklist, business calendars, WLXT, XML, and so on.

Annotations Reference

Provides reference information about WebLogic Integration-specific Workshop annotations, which are formatted like Javadoc tags.

Samples

Explains how to use samples that demonstrate WebLogic Integration functionality.

Building and Deploying Integration Applications

References information about building and deploying applications

as enterprise archive (EAR) files and as exploded directories.

Building Portal Applications

Welcome to portal development. This section of the help system provides overview information, reference topics, and procedures that guide you through the portal development process using the WebLogic Workshop Portal Extensions.

The WebLogic Workshop Portal Extensions provide more than a powerful, flexible, extensible framework for surfacing applications in portals. They also provide personalization, campaign, and behavior tracking services, a rules engine, JSP tags, integration services, intelligent administration, reusable samples, and a complete API.

Choose from the following subsections to learn more about WebLogic Portal, explore the power of the product with tutorials and samples, start developing or integrating your own portal applications, or access reference information.

Overview

Introduces portals and the WebLogic Portal architecture and provides guidance on getting started with WebLogic Portal.

Developing Portal Applications

Provides instructions on adding portal functionality to existing applications, developing new portal applications, and building portlets. This section includes information on integrating Web applications, struts applications, and Web services; building Web, JSP, Java Page Flow, and commerce applications; and creating portlets.

Developing Personalized Applications

Provides instructions for adding personalization and campaigns to your portal applications.

Developing Portal User Interfaces

Describes the WebLogic Portal user interface framework and provides instructions for creating a portal user interface and developing user interface resources. This section also provides guidance on building user interfaces to address accessibility guidelines.

Assembling Portal Applications

Provides instructions for assembling portals with existing portal resources, such as creating a portal file, adding books and pages to desktops, changing page layouts, changing the look & feel, and changing the shell.

Securing Portal Applications

Describes the security touch points in a portal development scenario and provides links to instructions that relate to those touch points. This section also describes how WebLogic Portal implements the WebLogic Server security service provider interface (SSPI).

Deploying Portal Applications (edocs)

Provides detailed information and best practices for deploying portal applications.

Portal Reference

Includes Javadoc for WebLogic Portal and partner APIs, a WebLogic Portal JSP tag reference, WebLogic Portal samples, and other reference information.

What is a Portal?

A portal represents a Web site that provides a single point of access to applications and information and may be one of many hosted within a single WebLogic Portal server.

Portals are becoming more and more important to companies, who have an ever-increasing need to provide employees, partners, and customers with an integrated view of applications, information, and business processes. WebLogic Portal meets these needs, allowing companies to build portals that combine functionality and resources into a single interface while enforcing business policies, processes, and security requirements, and providing personalized views of information to end users.

From an end user perspective, a portal is a Web site with pages that are organized by tabs or some other form of navigation. Each page contains a nesting of sub-pages, or one or more portlets—individual windows that display anything from static HTML content to complex Web services. A page can contain multiple portlets, giving users access to different information and tools in a single place. Users can also customize their view of a portal by adding their own pages, adding the portlets they want to it, and changing the look and feel of the interface.

The business problem that portals solve is illustrated in the following example. A company has the need for several types of Web presence: an Intranet for its employees, a secure site for interactions with partners, and a public Web site. WebLogic Portal’s flexible portal network architecture supports multiple implementation choices which allow re-use of resources across portals.

Portals in Java 2 Enterprise Edition (J2EE) Terms

From a J2EE standpoint, WebLogic Portal is an enterprise application consisting of Enterprise Java Bean (EJB) components and a set of Web applications. The enterprise application contains the core application programming interfaces (API), and the Web applications contain servlets, Java Server Pages (JSPs), JSP tag libraries, and supporting Java classes.

The WebLogic Portal architecture allows multiple portals per Portal Web application, letting you flexibly build and leverage Web application resources and security in multiple portal deployments.

Technically speaking, a portal is a container of resources and functionality that can be made available to end-users. These portal views, which are called Desktops in WebLogic Portal, provide the uniform resource location (URL) that users access.

Components that Make up a Portal

In WebLogic Portal, a portal definition is a single XML file. The XML file is created automatically as you build a portal with the Portal Designer that is provided as part of the WebLogic Workshop Portal Extensions. The portal file contains all the components that make up that particular instance of the portal, such as books, pages, portlets, and look and feel components.

Many components have a hierarchical relationship to each other. For example, a book contains pages and pages contain portlets. The Document Structure illustration shows the relationship between components in a portal file. Following are descriptions of the components that make up a portal interface.

Desktop - A desktop is is an audience specific view of portal components. It contains the portal header, footer, and body. The body contains the bulk of the portal content: books, pages, portlets, and look and feel elements. A portal can support one or more desktops. After a portal administrator sets entitlements on the desktop and makes it ready for public consumption, the desktop is the view of the portal accessed by end users. From there, users may configure their own views through customization of the desktop. Think of a desktop as a user view of a Web site or a portal, exposing a different set of information or tools based on user context. For example, each department in an organization (Human Resources, Accounting, Legal, Sales) can define a portal desktop containing its own portlets, navigation, and look and feel, yet these desktops are all supported by a single portal definition.

Shell - A desktop's header and footer, controlled by a portal shell (.shell file), are the areas that are typically above and below the main body. These areas usually display such things as personalized content, banner graphics, legal notices, and related links.

Book - A Book is a component that provides high-level content organization and navigation. Books contains pages or other books, providing a mechanism for hierarchical nesting of pages and content. Books are identified by a control such as a tab set.

Page - Pages contain the portlets that display the actual portal content. Pages can also contain books and other pages. Pages are identified by a control such as a tab set.

Layout and Placeholder - A layout is an HTML table definition used by a page to determine the physical locations of portlets on the page. Administrators and users can choose different available layouts for pages. Placeholders are the individual cells in a layout in which portlets are placed.

Portlet - Portlets are the windows that surface your applications, information, and business processes. They can contain anything from static HTML content to Java Controls to complex Web services and process-heavy applications. Portlets can communicate with each other and take part in Java Page Flows that use events to determine a user's path through an application. You can have multiple portlets on a page. You can also have multiple instances of a single Portlet. For example, you can put instances of a portlet on multiple pages; so that if users don't have rights to view one page with that portlet on it, they can see the portlet on a page they do have rights to view. Portlets can have different modes, such as minimize, maximize, edit, delete, configure, and help, selectable from their title bars.

Portal Rendering and Look and Feel Components (not shown in the illustration) - A desktop's appearance is determined by the Look and Feel. A look and feel definition contains two major elements: skins and skeletons.

Skins - Skins provide the overall colors, graphics, and styles used by all components in a desktop interface. Skins are collections of graphics and cascading style sheets (CSS) that allow changes to be made to the look and feel of a portal without modifying the portal components directly. References to images and styles are made in the skin rather than being hard coded into the portal definition. The look and feel file provides a path to the skin directory to be used. Themes are subsets of skins that you can apply to books, pages, and portlets, providing a way of using a different set of styles for individual desktop components.

Skeletons - The look and feel file also provides a path to the skeleton directory to be used. Every type of component, from a desktop to a portlet's title bar, has an associated JSP file, called a skeleton file, that renders it. Some skeleton files are simple, others are more complex. For example, each desktop uses a skeleton file called shell.jsp that simply provides the opening and closing tags to render the desktop. A portlet title bar, on the other hand, has a skeleton file called titlebar.jsp that is more complex. It contains Java calls to various windowing methods in the API, references the button graphics to use on the title bar, and determines the placement of title bar elements with an HTML table definition.

After the logic in the skeleton servlets executes for a look and feel, components are rendered hierarchically into a single HTML instance that is the user view of the desktop.

Administrators and users can select from a list of available look and feel definitions, which changes the appearance, and sometimes the behavior, of a user's view of a desktop. For example, the header of one look and feel can contain a static graphic, while the header of another look and feel can contain a campaign that targets a user with personalized content from a content repository.

Portal Development Tools and Services

WebLogic Portal includes many powerful tools and services that make portal development fast and easy.

Designers and Samples - The WebLogic Workshop Portal Extensions include a Portal Designer and a Portlet Designer that provide graphical drag and drop functionality and grid-based property setting, letting you create a sophisticated portal in minutes. For example, you can create a portal file (that

appears with a default page), drag one of the sample JSPs from the file tree onto the default page, and a portlet is created for you automatically. You can then save the file and view the portal desktop in a browser.

Java Controls - WebLogic Workshop Enterprise Edition includes many powerful Java Controls that insulate developers from lower-level coding, reducing the lines of code they must write (and therefore reducing the number of bugs). WebLogic Portal provides several Java Controls to assist development of personalized applications, such as a User Profile Control and a Display Content Control.

Portal Java Controls increase developer productivity for application development. Instead of writing code to access an API or J2EE resource directly or even using JSP tags, a developer can insert the User Profile Control into a JSP or Java Page Flow and select the appropriate methods for retrieving and updating user profile information, determining whether or not a user exists, or retrieving a list of users based on search parameters.

JSP Tags - The WebLogic Workshop Portal Extensions include a library of JSP tags that let you perform useful tasks in JSPs with minimal coding.

Content Management - WebLogic Portal includes powerful content management functionality, letting you integrate and manage multiple content management systems in a single virtual content repository. As a developer you can query the repository and retrieve and display personalized content in your portal applications. The Virtual Content Repository is set up and managed in the WebLogic Administration Portal and supports the full development lifecycle.

Unified User Profile - WebLogic Portal includes a unified user profile service that lets you add, access, and manage users and their properties in a single logical location—even if the base set of user data is stored on an external system such as an LDAP server. The unified user profile is a key element in such things as triggering personalization, setting role-based administration, and creating end user entitlements to portal resources.

Personalization, Interaction Management, and Behavior Tracking - The Portal Resources Designer lets you define the properties, rules, and actions that display personalized Web content to users, send automatic e-mails, or provide automatic discounts. The designer lets you create campaigns, content selectors, placeholders, and user profile and other properties. The WebLogic Workshop Portal Extensions also provide a set of events for tracking user behavior in portals, and the designer lets you register any custom events you develop.

APIs - WebLogic Portal includes an extensive set of APIs you can use directly for custom application development. For example, the Expressions Package provides a set of expressions that let you construct complex content queries.

Creating a Portal

Creating a portal involves using the WebLogic Portal framework and tools to surface applications in a portal user interface. It also involves adding personalization, campaigns, and behavior tracking to your applications.

You can quickly and easily integrate your own applications into WebLogic Workshop and apply WebLogic Portal's framework, tools, and services to them, or you can create new portal applications in WebLogic Workshop.

The following sections guide you through the process of creating a portal:

Developing Portal Applications

Provides instructions on adding portal functionality to existing applications, developing new portal applications, and building portlets. This section includes information on integrating Web applications,

struts applications, and Web services; building Web, JSP, Java Page Flow, and commerce applications; and creating portlets.

Developing Personalized Applications

Provides instructions for adding personalization and campaigns to your portal applications.

Developing Portal User Interfaces

Describes the WebLogic Portal user interface framework and provides instructions for creating a portal user interface and developing user interface resources. This section also provides guidance on building user interfaces to address accessibility guidelines.

Assembling Portal Applications

Provides instructions for assembling portals with existing portal resources, such as creating a portal file, adding books and pages to desktops, changing page layouts, changing the look & feel, and changing the shell.

Creating a Portal Application and Portal Web Project

To create the necessary resources for portal development, you must do one of two things:

Option 1: Create a new portal application and add a Portal Web Project to it

or Option 2: Install Portal into an existing application and add a Portal Web Project to it

Following are the procedures for each option.

Option 1: To create new portal application and add a Portal Web project to it

Use this procedure to create a new portal application.

You do not need to perform these steps if you are developing on a shared domain and the portal application has already been created and stored in a version-control system. Simply synchronize to the current version of the domain to put the portal application on your machine.

1. If you have not yet created a portal domain on your development machine, create one with the Configuration Wizard. For instructions, see the Overview of Platform Configuration on the BEA's e-docs Web site.

Performing this step ensures you have a server (config.xml) for your portal application to use, as described later in this procedure.

2. Create a new portal application. In WebLogic Workshop Platform Edition, choose File -->New -->Application.

3. In the New Application window, select Portal Application in the right pane.4. In the Directory field, click Browse to set the location of the new application. The application

will be created in a subdirectory of the directory you select.5. Make sure the Name field contains the name of the application. This name will be the

application directory. 6. In the Server field, click Browse and select the config.xml file for the server (domain) you

want to use.

The config.xml file is in the portal domain directory you created.

7. Click Create. The application directory appears in the Application window. The application contains the WebLogic Administration Portal (contained in Modules/adminPortal.war), a datasync directory (data) for interaction management development, and application-level EJBs and APIs.

8. Create a portal Web project for your application. Right-click the directory in the Application window, and choose New -->Project.

9. In the New Project window, select Portal Web Project in the right pane. 10. In the Project name field, enter the name for the portal Web project. This will be the name of

a Web application directory. 11. Click Create. The project folder appears in the Application window. The portal Web project

contains WebLogic Portal JSP tags, Web-application-level APIs, and default portal framework files.

12. If you have any external projects or files you want to include in your portal application, perform any of the following steps:

o To import a project, right-click the directory in the Application window and choose Import Project. In the Import Project window, select the type of project to import, browse to select the project folder, and click Import.

o To import files, such as existing datasync files (User Segments, Campaigns, Placeholders, and so on) or the Workshop Portal Extensions sample portlets to use in your portals , right-click the appropriate directory in the Application window and choose Import. In the Import Files window, select the directory or files you want to import, and click Import.

The sample portlets are located in \\samples\portal\portalApp\sampleportal\portlets. There are other useful sample files throughout the \\samples directory. See the instructions in Portal Samples for more information.

You now have the resources and directories for developing personalized applications and creating portals to surface applications.

13. Start your development server. In WebLogic Workshop, choose Tools-->WebLogic Server-->Start WebLogic Server. The server you assigned to your application in the previous steps starts. All your work is deployed automatically on your machine as you develop.

Option 2: To install portal in an existing application and add a Portal Web project to it

Use this procedure to add portal services to an existing application.

You do not need to perform these steps if you are developing on a shared domain and the portal-enabled application has already been created and stored in a version-control system. Simply synchronize to the current version of the domain to put the portal application on your machine.

1. In WebLogic Workshop Platform Edition, open the application in which you want to install portal.

2. In the Application window, right-click the directory and choose Install-->Portal. WebLogic Workshop adds the WebLogic Administration Portal (contained in Modules/adminPortal.war), a datasync directory (data) for interaction management development, and application-level EJBs and APIs.

3. Create a portal Web project for your application. Right-click the directory in the Application window, and choose New-->Project.

4. In the New Project window, select Portal Web Project in the right pane. 5. In the Project name field, enter the name for the portal Web project. This will be the name of

a Web application directory. 6. Click Create. The project folder appears in the Application window. The portal Web project

contains WebLogic Portal JSP tags, Web-application-level APIs, and default portal framework files.

7. If you have any external projects or files you want to include in your application, perform any of the following steps:

o To import a project, right-click the directory in the Application window and choose Import Project. In the Import Project window, select the type of project to import, browse to select the project folder, and click Import.

o To import files, such as existing datasync files (User Segments, Campaigns, Placeholders, and so on) or the Workshop Portal Extensions sample portlets to use in your portals , right-click the appropriate directory in the Application window and choose Import. In the Import Files window, select the directory or files you want to import, and click Import.

The sample portlets are located in \\samples\portal\portalApp\sampleportal\portlets. There are other useful sample files throughout the \\samples directory. See the instructions in Portal Samples for more information.

You now have the resources and directories for developing personalized applications and creating portals to surface applications.

8. Start your development server if it is not already running. In WebLogic Workshop, choose Tools-->WebLogic Server-->Start WebLogic Server. All your work is deployed automatically on your machine as you develop.

Developing Enterprise JavaBeans

These topics show how to develop Enterprise JavaBeans. WebLogic Workshop provides you with the tools to make EJB development much easier, taking care of many implementation details for you and allowing you to focus on design.

Note. WebLogic Workshop 8.1 supports the development, importing, and building of EJB2.0 compliant Enterprise JavaBeans. In addition, the WebLogic Platform supports the deployment only of EJB1.1 compliant Enterprise JavaBeans.

Getting Started with EJB Project

When you are building WebLogic platform applications, EJB project is the development environment for Enterprise JavaBeans. EJB project provides a number of tools that facilitate the development of the EJBs which encompass the business logic for your enterprise application. This topic provides an overview of EJBs and EJB project in platform applications. It includes the following sections:

What is an Enterprise JavaBean? What is EJB Project? EJB Project and ejbgen Tags Building and Deploying EJBs What are EJB Controls?

What is an Enterprise JavaBean?

An EJB is a server-side component that encapsulates the business logic of an application. The business logic is the code that fulfills the purpose of the application, as opposed to code that provides infrastructure and plumbing for the application. In an inventory control application, for example, the EJBs might implement the business logic in methods called checkInventoryLevel and orderProduct. By invoking these methods, remote clients can access the inventory services provided by the application.

EJBs always execute within an EJB container, which provides system services to EJBs. These services include transaction management, persistence, pooling, clustering and other aspects of infrastructure. The J2EE and EJB architecture is built on a number of underlying technology standards, such as the JDBC API for database connectivity, JMS for messaging, and JNDI for naming and directory functionality. To learn more about these technology standards, see your favorite J2EE documentation and http://java.sun.com.

In J2EE 1.4 there are three types of EJBs: session, entity, and message-driven. Each of these types is described briefly in the following sections.

Session EJBs

A session EJB is used to execute business tasks for a client on the application server. The session EJB might execute only a single method for a client, in the case of stateless session beans, or it might execute several methods for that same client, in the case of stateful session beans. A session bean is never shared by clients. A session EJB is not persistent, so when the client terminates, its session EJB disconnects and is no longer associated with the client.

Entity EJBs

An entity EJB represents a business object in a persistent storage mechanism. Some examples of business objects are customers, orders, and products. The persistent storage mechanism is a relational database. Typically, each entity bean has an underlying table in a relational database, and each instance of the bean corresponds to a row in that table. Unlike session beans, entity beans are persistent, allow shared access, have primary keys, and may participate in relationships with other entity beans.

Message-Driven EJBs

A message-driven EJB is an enterprise bean that is able to listen for Java Message Service (JMS) messages. The messages may be sent by any JMS-compliant component or application. Message-driven EJBs provide a mechanism for J2EE applications to participate in relationships with message-based legacy applications.

EJB Interfaces

EJB 2.0 exposes four types of interfaces for session and entity beans, called the local home interface, the local business interface (or simply, the local interface), the remote home interface, and the remote business interface (or simply, the remote interface). Client applications can obtain an instance of the EJB with which to communicate by using the remote home interface. The methods in the remote home interface are limited to those that create or find EJB instances. Once a client has an EJB instance, it can invoke methods of the EJB's remote business interface to do real work. The business interface directly accesses the business logic encapsulated in the EJB. Interactions between EJBs defined in the same WebLogic Workshop application, as well as interactions between EJBs and web services or page flows in the same WebLogic Workshop application, can use the local interfaces instead, which provides a performance advantage over remote interfaces. In other words, the local home and business interfaces define the methods that can be accessed by other beans, EJB controls, web services, and page flows in the same WebLogic Workshop application, while the remote home and business interfaces define the methods that can be accessed by other applications.

Message-driven beans do not have these interfaces, because these beans' methods do not get invoked directly by other beans or client applications. Instead they process messages from client applications or other EJBs that are delivered via the Java Message Service (JMS). When a message is delivered, the EJB container calls the message-driven bean's onMessage method to process the message. For more information on Java Message Service, see your favorite J2EE documentation. WebLogic Workshop also provides JMS controls to work with a Java Message Service. For more information, see JMS Controls.

Deployment Descriptor

During runtime, information about how EJBs should be managed by the EJB container is read from a deployment descriptor. The deployment descriptor describes the various beans packaged in an EJB JAR file, settings related to transaction management, and EJB QL for find methods, to name a few examples. Deployment descriptor settings can be changed without having to make changes to the actual beans, allowing for the fine-tuning of EJBs.

EJB JAR

The EJB JAR contains one or more EJBs, including their interface definitions, any related Java classes that are being used by the EJBs, and a deployment descriptor describing these EJBs.

What is EJB project?

EJB project is the development environment for session, entity, and message-driven beans in a WebLogic platform application. An EJB project contains one or more EJBs. A WebLogic platform application can have one or more EJB projects, as well as other types of projects such as web (service) projects, and Java control projects, thereby creating an integrated development environment.

EJB project provides a Design View, property editor, building and debugging windows, and various wizards to facilitate the design and development of EJBs. For instance, in Design View you can define business (component) methods, define CMP fields, and define methods for local and/or remote interfaces. A property editor is used to edit deployment descriptor settings and ejbgen tag settings (see below). Various wizards make it easy to import EJBs into EJB projects, create ejbCreate methods, and define entity relationships. Build and debugging windows are used to monitor the build process and to monitor the EJB when running/debugging the application. For more information on the visual environment, see Summary of IDE Windows for EJB Project. For step-by-step instructions on using the Design View and the various wizards, see the 'How Do I...?' section Enterprise JavaBeans.

A key advantage of developing EJBs in EJB project is that one file is used to store the definition of the EJB class, its interfaces, and deployment descriptor specific settings. Instead of managing the overhead of using several java files to store this information, one file with an ejb extension is used to represent an EJB. This is accomplished by using ejbGen, which is described next.

EJB Project and ejbgen Tags

During Enterprise JavaBean development, special Javadoc tags with the prefix ejbgen are inserted in the EJB source file. These ejbgen tags are used to mark methods to be exposed in remote and home interfaces, store deployment descriptor settings, and various other types of information. In many cases you will not have to add these ejbgen tags directly. Instead these tags are added when, for example, you define a business methods to be local, or create a primary key field for an entity bean. You can also use the property editor to edit ejbgen tag settings.

The use of a single EJB file is only for development purposes. When you build an EJB Project, the build process uses these tags to generate the various interfaces and deployment descriptor files as prescribed in the J2EE specification.

Building and Deploying EJBs

When you build an EJB project, the EJBs' source code is compiled and checked for errors. The build output of an EJB project is an EJB JAR, containing the various JAVA and CLASS files for the bean class, its interfaces, and any dependent value or primary key classes, as well as the deployment descriptor for these beans. After the build completes, the beans are (re)deployed on the server. You can also deploy, undeploy and redeploy EJBs separately from building.

What are EJB Controls?

When you want to use an EJB from a client application (such as a page flow), you must look up the EJB in the JNDI registry and obtain the EJB's home interface, before you can create an EJB instance and invoke the EJB's business methods. EJB controls provide an alternative approach to make locating and referencing the EJB easy. Once you have created the EJB control, the client application can define the EJB control and use its methods, which have the same method names as the EJB it controls, to execute the desired business logic without having to be involved with locating and referencing the EJB itself. In other words, EJB controls take care of the preparatory work necessary to use an EJB, allowing you to focus on the business logic instead. For more information, see EJB Controls.

What are CMP Entity Beans?

An entity bean represents a business object in a persistent storage mechanism. In other words, entity beans are used to model real-world objects with properties that need to be stored and remembered over time. Examples of business objects are customers, products, orders, credit cards, and addresses. Typically, each entity bean has an underlying table in a relational database, and each bean instance corresponds to a row in that table. An entity bean has one or more primary keys, or unique indices, to uniquely identify an object, that is, a particular record in the database.

Container-managed persistence (CMP) entity beans are entity beans for which the EJB container takes care of mapping property and relationship fields to the underlying database and knows how to insert, update, and delete data for an entity bean.

Home and Business Interfaces

An entity bean can have four different interfaces, called the local home interface, the local business interface (or simply, the local interface), the remote home interface, and the remote business interface (or simply, the remote interface). The local interfaces define the bean's methods that can be used by other EJBs, EJB controls, web services, and page flows defined within the same application. That is, if you define an entity bean and only plan to use it within that application, you can use local interfaces. In contrast, the remote interfaces define the bean's methods that be invoked by EJBs, EJB controls, web services, and page flows defined in other applications.

To determine what interfaces are defined for an entity bean, ensure you are in Design View and go to the Naming section in the Property Editor. The Remote EJB and Local EJB sections refer to the remote and local interfaces; within each section the Home class name refers to the home interface, and the Bean class name refers to the business interface. In Source View, the attributes are part of the @ejbgen:file-generation Annotation. When you define a new entity bean, by default only the local interfaces are defined, reflecting the design assumption that in your model entity beans are not accessed directly by other client applications but indirectly, with session or message-driven beans defined in the same application as intermediaries.

Client applications and other session or entity beans can obtain an instance of an entity bean with which to communicate by using methods in the (remote or local) home interface. Methods in the home interface include create methods, the findByPrimaryKey method, and other finder methods that return a single reference or a set of references to entity bean instances. In addition, Home methods are defined in the local interface. The (remote or local) business interface contains the methods that manipulate an entity bean instance. These methods include field accessor (getter and setter) methods and component methods.

CMP Fields

Container-managed persistence (CMP) fields contain the business object's properties. For example, a Customer bean might contain first name, last price, gender, and age fields. Because the EJB container takes care of the mapping of these properties to a database, CMP fields are virtual fields in an entity bean; that is, these fields are not defined in the entity bean itself but correspond to columns in the

database table. The entity bean only defines the accessor (getter and setter) methods. A CMP field can serve as a primary key field, meaning that this field uniquely identifies the entity bean instance or, if multiple primary keys are defined, in combination with the other primary keys uniquely identifies the entity bean instance. For more information, see How Do I: Define a Container-Managed Persistence (CMP) Field?

Create Methods

An ejbCreate method is used to create a new instance of an entity bean, that is, insert a new record in the underlying database. At least one ejbCreate method must be defined, but multiple ejbCreate methods are not uncommon. Each ejbCreate method defined for an entity bean has the signature public ejbCreate(parameters). The can be a primitive type, such as Integer, when a single primary key is defined, or it can be a separate primary key class. By default, WebLogic auto-generates a primary key class, with the name provided as an attribute in the @ejbgen:file-generation Annotation. To find out which primary key class is used for an entity bean, ensure you are in Design View and go to the General section in the Property Editor. In Source View, this attribute is part of the @ejbgen:entity Annotation.

Multiple ejbCreate methods can only be distinguished by their parameter composition. In the home interface, ejbCreate methods are exposed as create methods and can correspondingly be distinguished only by the unique set of parameters each one requires. For more information, see How Do I: Add a Create Method to an Entity Bean?

Component Methods

Component methods are the business methods that are invoked on an entity bean instance. A simple example of a business method is updateCustomer(firstName, lastName, age), which is used to update the customer's first name, last name and age. This method will in turn invoke the bean's setFirstName, setLastName and setAge methods to update the CMP fields holding this information. For more information, see How Do I: Add a Component Method to an Entity or Session Bean?

Home Methods

A home method is a business method that relates to the entity bean but is not specific to a single bean instance. For instance, a Customer bean might have a home method returning the total number of customers between 25 and 35 years of age. A home method is defined as a ejbHome method in the bean, and is exposed as a method on the bean's home interface. For example the method ejbHomeGetNCustomers defined in the bean class is exposed as getNCustomers in its home interface. For more information, see How Do I: Add a Home Method to an Entity or Session Bean? and the Home Methods Sample.

Finder and Select Methods

Finder and select methods are methods that execute queries on the database, using the EJB QL or WebLogic QL query languages. A finder method is defined in the bean's home interface and returns a reference to a single bean instance or to a set of references to bean instances. In contrast, a select method is not defined in any interface and can only be invoked internally, for instance by a bean's component method. A select method can return a reference to a single bean instance, a set of bean instances, or one or more individual CMP fields.

In addition to the finder and select methods defined for the bean, the method findByPrimaryKey() is automatically defined by WebLogic in the home interface(s) defined for the bean class. This method returns a reference to the bean instance that is uniquely defined by the method's parameter. As before, the can be a primitive type, such as Integer, when a single primary key is defined, or it can be a separate primary key class. To find out which primary key class is used for an entity bean, ensure you are in Design View and go to the General section in the Property Editor. In Source View, this attribute is part of the @ejbgen:entity Annotation.

For more information on how to define finder or select methods, see How Do I: Add a Finder Method to an Entity Bean? and How Do I: Add a Select Method to an Entity Bean? For more information on the EJB QL and WebLogic QL query languages, see Query Methods and EJB QL, the Finder Methods Sample, and the Select Methods Sample.

Relations

Entity relationships are used to model dependencies between business objects. For example, a customer can have one or more credit cards, and a product has a manufacturer. Relations between two entity beans can be defined such that for a customer, you can easily access its credit cards by using the accessor method getCreditCards. The entity relation accessor methods, also known as the CMR field accessor methods are defined in the bean's business interface. For more information, see Entity Relationships, How Do I: Add a Relation to an Entity Bean?, and Tutorial: Enterprise JavaBeans.

Other Methods

An entity bean has several predefined methods, as well as a number of callback methods, invoked by the EJB container during certain operations, that an entity bean must implement. In WebLogic these callback methods are by default automatically implemented. In many cases you will find it unnecessary to use these methods, with the possible exception of the remove methods used to remove an entity bean instance. To learn more about predefined methods and remove methods in particular, see Defining an Entity Bean. To learn more about callback methods, see the Callback Methods section of that same topic and The Life Cycle of an Entity Bean.

Creating an Entity Bean

To create an entity bean, you can choose one of the following methods:

Create an entity bean from scratch. If you are designing a new entity bean in EJB project, you can define a new entity bean. To find out exactly how to do this, see How Do I: Create an Enterprise JavaBean? When you create a new entity bean, by default the local interfaces and various other defaults are defined. For more details, see @ejbgen:file-generation Annotation.

Create an entity bean from a database table. If you have already designed a database table and want to create an entity bean with CMP fields mapped to the database columns, you can create an entity bean from a database table. To find out exactly how to do this, see How Do I: Generate an Entity Bean from a Database Table? In addition to mapping the CMP fields and defining an ejbCreate method with the (compound) primary key as the parameter, by default local interfaces and various other defaults are defined. For more details, see @ejbgen:file-generation Annotation. After you have created an entity bean from a database table, you can further expand its definition, including making changes that will require changes to the underlying database table.

Import an entity bean. If you have developed entity beans in another development environment, you can import these into WebLogic. To import an EJB, you need the EJB Jar file as well as the source files. You can import multiple EJBs at the same time. If you import multiple entity beans with defined entity relations, these relation definitions will be imported as well. For more information, see How Do I: Import an Enterprise JavaBean? After you have imported an entity bean, you can enhance its definition.

Note. If you have existing entity beans that you plan to invoke in the application, for instance via another EJB or an EJB control, but you do not intend to change their definitions, you can suffice by adding the EJB Jar to the application. For more information, see How Do I: Add an Existing Enterprise JavaBean to an Application?

Automatic Table Creation

When you are developing a new entity bean using any of the three methods specified above, you can make iterative development easier by enabling automatic table creation. You can have WebLogic create the table when it is not present, and you can allow WebLogic to drop an existing table and recreate it if the definition of the entity bean does not match the table specifications. You enable automatic table creation using the create-table property located in the JAR Settings section of the Property Editor. The default setting is CreateOnly. To recreate a table if the definition of the entity bean does not match the table specification, use DropAndCreate. For more information regarding the possible settings, see @ejbgen:jar-settings Annotation.

Note. Automatic table creation is meant to facilitate development, and is disabled in production mode.

Defining a Basic Entity Bean

The following figure shows the design view of a basic entity bean called ProductBean:

This bean was developed by defining it from scratch, adding the two CMP fields, labeling one of these as the primary key, and creating an ejbCreate method (for more details, see How Do I: Add a Create Method to an Entity Bean?). These steps were accomplished in design view. This entity bean allows you to add a new product, find a product using its primary key, and getting and setting its CMP field values. The source code of this bean is given below:

package myBeans;

import javax.ejb.*;import weblogic.ejb.*;

/** * @ejbgen:entity prim-key-class="java.lang.String" * ejb-name = "Product" * data-source-name="cgSampleDataSource" * table-name = "product" * abstract-schema-name = "Product" * * @ejbgen:jndi-name * local = "ejb.ProductLocalHome"

* * @ejbgen:file-generation local-class = "True" local-class-name = "Product" local-home = "True" * local-home-name = "ProductHome" remote-class = "False" remote-home = "False" remote-home-name = "ProductRemoteHome" * remote-class-name = "ProductRemote" value-class = "False" value-class-name = "ProductValue" pk-class = "True" * */abstract public class ProductBean extends GenericEntityBean implements EntityBean{

/** * @ejbgen:cmp-field primkey-field="true" column="Name" * @ejbgen:local-method */ public abstract String getName();

/** * @ejbgen:local-method */ public abstract void setName(String arg);

/** * @ejbgen:cmp-field column="Price" * @ejbgen:local-method */ public abstract double getPrice();

/** * @ejbgen:local-method */ public abstract void setPrice(double arg);

public java.lang.String ejbCreate(java.lang.String Name, double Price) { setName(Name); setPrice(Price);

return null; // FIXME return PK value }

public void ejbPostCreate(java.lang.String Name, double Price) { }}

In WebLogic, all the information needed to make an entity bean is stored in a single file, instead of separate JAVA files for the bean class, the local business interface, the local home interface, its primary key class, and so forth. When you build an EJB, these other classes are auto-generated. Various ejbgen annotations are used to hold the information required to make this generation possible. For example, the @ejbgen:file-generation annotation specifies the names of the local home and business interface for the ProductBean. The @ejbgen:local-method annotations on the accessor methods specify that these methods are defined in the local business interface. To verify that these JAVA and corresponding CLASS files are generated, expand the JAR file created during a build (located in the Modules folder in the Application pane), and locate and open the generated files in the folder reflecting the package name. For the ProductBean, the ProductBean.java (bean definition), Product.java (local interface definition), and ProductHome.java (local home interface definition) files are auto-generated.

If the ProductBean were to use multiple primary keys, the ProductBeanPK.java file containing the definition of the compound primary key class would also be auto-generated. For instance, the following figure shows a redefined ProductBean with an additional primary key manufacturer:

Notice in the above figure that the compound primary key is the return value of the ejbCreate method. Also, the auto-generated method findByPrimaryKey(myBeans.ProductBeanPK primaryKey) uses the compound primary key to obtain a bean instance reference.

Finally a value object class can also be auto-generated. For more information, see the Value Object Sample

Removing an Entity Bean Instance

Any entity bean must define at least one ejbCreate method to create a new instance. Also, the EJB container automatically defines the findByPrimaryKey method in the home interface(s), which return a bean instance using its primary key (class) as the method parameter. In addition, all the bean's interfaces will extend a particular interface which contains various useful methods. Specifically:

The local interface extends javax.ejb.EJBLocalObject The local home interface extends javax.ejb.EJBLocalHome The remote interface extends javax.ejb.EJBObject The remote home interface extends javax.ejb.EJBHome

Complete details about these interfaces and the methods they define can be found in your favorite J2EE documentation and the API reference at http://java.sun.com. One of the more frequently used methods provided by these 'extended' interfaces is a remove method, used to remove an entity bean instance. In other words, when you invoke the remove method on an entity bean, you remove the bean and the underlying record in the database. Remove methods are defined in all the interfaces. For instance, to remove a bean instance via the local home interface, you can invoke a remove method that takes instance's primary key as the parameter. To remove a bean instance via the local interface, you can invoked the remove method for the instance you want to remove. Both approaches are shown below; the session bean's method deleteViaHome deletes an instance of the Product bean via its local home interface, while deleteViaBusiness delete a Product bean instance via the local interface:

/**

* ... * * @ejbgen:ejb-local-ref link="Product" */public class SomeSession extends GenericSessionBean implements SessionBean{ ...

/** * @ejbgen:local-method */ public void deleteViaHome(myBeans.ProductBeanPK thePk) { try { javax.naming.Context ic = new InitialContext(); ProductHome productHome = (ProductHome)ic.lookup("java:comp/env/ejb/Product"); productHome.remove(thePk); } catch(NamingException ne) { ... } catch(RemoveException re) { ... } }

/** * @ejbgen:local-method */ public void deleteViaBusiness(myBeans.ProductBeanPK thePk) { try { javax.naming.Context ic = new InitialContext(); ProductHome productHome = (ProductHome)ic.lookup("java:comp/env/ejb/Product"); Product theProduct = productHome.findByPrimaryKey(thePk); theProduct.remove(); } catch(NamingException ne) { ... } catch(FinderException ne) { ... } catch(RemoveException re) { ... } }

...}

Callback Methods

Every entity bean must implement the javax.ejb.EntityBean interface. This interface defines callback methods that are called by the EJB container at specific times. The callback methods are setEntityContext, unsetEntityContext, ejbActivate, ejbPassivate, ejbLoad, ejbStore, and ejbRemove. When you define an entity bean from scratch or via a database table, it will extend weblogic.ejb.GenericEntityBean, which contains empty implementations of these callback methods. In other words, you will only need to define these methods if you need to override the empty

implementation. If you import an entity bean, these callback methods will probably be implemented directly in the bean's ejb file.

For more details about the callback methods and their role in the interaction between the entity bean and the EJB container, see The Life Cycle of an Entity Bean.

Automatic Primary Key Generation

In WebLogic it is possible to automatically generate a primary key to be used when creating a new CMP entity bean instead of providing primary key values. You can auto-generate primary keys in various vendor-specific ways - using Oracle, SQLServer, or SQLServer2000 - or you can use a vendor-neutral named sequence table. In all cases auto-generated primary keys are of type Integer or Long.

The topics in this section are:

Primary Key Generation Using Oracle's Sequence Primary Key Generation Using SQL Server's IDENTITY Primary Key Generation Using a Named Sequence Table Defining the CMP Entity Bean

Primary Key Generation Using Oracle's Sequence

Oracle provides the 'sequence' utility to automatically generate unique primary keys. To use this utility to auto-generate primary keys for a CMP entity bean, you must create a sequence table and use the ejbgen:automatic-key-generation tag to point to this table.

In your Oracle database, you must create a sequence table that will create the primary keys, like is shown in the following example:

create sequence myOracleSequencestart with 1 nomaxvalue;

This creates a sequences of primary key, starting with 1, followed by 2, 3, and so forth. The sequence table in the example uses the default increment 1, but you can change this by specifying the increment keyword, such as increment by 3. When you do the latter, you must specify the exact same value in the cache-size attribute of the ejbgen:automatic-key-generation tag:

@ejbgen:automatic-key-generation type="Oracle" name="myOracleSequence" cache-size="3"

If you have specified automatic table creation in the CMP bean's project settings, the sequence table will be created automatically when the entity bean is deployed. For more information, see @ejbgen:jar-settings Annotation. For more information on the definition of a CMP entity bean, see below.

Primary Key Generation Using SQL Server's IDENTITY

In SQL Server (2000) you can use the 'IDENTITY' keyword to indicate that a primary-key needs to be auto-generated. The following example shows a common scenario where the first primary key value is 1, and the increment is 1:

CREATE TABLE Customer (Customer_ID int IDENTITY(1,1), FirstName varchar(30) LastName varchar(30))

In the CMP entity bean definition you need to specify SQLServer(2000) as the type of automatic key generator you are using. You can also provide a cache size:

@ejbgen:automatic-key-generation type="SQLServer"

If you have specified automatic table creation in the CMP bean's project settings, the sequence table will be created automatically when the entity bean is deployed. For more information, see @ejbgen:jar-settings Annotation. For more information on the definition of a CMP entity bean, see below.

Note. The SQLServer2000 option is the same as SQLServer, except that SQLServer uses @@IDENTITY column to get the generated key value and SQLServer2000 uses the SCOPE_IDENTITY() function instead.

Primary Key Generation Using a Named Sequence Table

A named sequence table is similar to the Oracle sequence functionality in that a dedicated table is used to generate primary keys. However, the named sequence table approach is vendor-neutral. To auto-generate primary keys this way, create a named sequence table using the two SQL statements shown in the example:

CREATE Table MyNamedSequence (SEQUENCE number);INSERT into MyNamedSequence VALUES (0);

In the CMP entity bean definition you need to specify the named sequence table as the type of automatic key generator you are using. You can also provide a cache size:

@ejbgen:automatic-key-generation name="MySequence" type="MyNamedSequenceTable" cache-size="100"

If you have specified automatic table creation in the CMP bean's project settings, the sequence table will be created automatically when the entity bean is deployed. For more information, see @ejbgen:jar-settings Annotation. For more information on the definition of a CMP entity bean, see the next section.

Note. When you specify a cache-size for a named sequence table, a series of unique values are reserved for entity bean creation. When a new cache is necessary, a second series of unique values is reserved, under the assumption that the first series of unique values was entirely used. This guarantees that primary key values are always unique, although it leaves open the possibility that primary key values are not necessarily sequential. For instance, when the first series of values is 10...20, the second series of values is 21-30, even if not all values in the first series were actually used to create entity beans.

Defining the CMP Entity Bean

When defining a CMP entity bean that uses one of the primary key generators, you point to the name of the primary key generator table to obtain primary keys, using the ejbgen:automatic-key-generation tag. Also, you must define a primary key field of type Integer or Long, to set and get the auto-generated primary key. However, the ejbCreate method does not take a primary key value as an argument. Instead the EJB container adds the correct primary key to the entity bean record.

The following example shows what the entity bean might look like. Notice that the bean uses the named sequence option describe above, and that ejbCreate method does not take a primary key: /** * @ejbgen:automatic-key-generation name="MyNamedSequence" type="NamedSequenceTable" cache-size="100" * * @ejbgen:entity prim-key-class="java.lang.Integer" * ejb-name = "Customer"

* data-source-name = "MyCustomerDataSource" * table-name = "customer" * abstract-schema-name = "Customer" * * ... */abstract public class Customer extends GenericEntityBean implements EntityBean{ ...

/** * @ejbgen:cmp-field primkey-field="true" column="Customer_ID" * @ejbgen:local-method */ public abstract Integer getCustomer_ID();

/** * @ejbgen:local-method */ public abstract void setCustomer_ID(Integer arg);

public java.lang.Integer ejbCreate(java.lang.String LastName, java.lang.String FirstName) { setLastName(LastName); setFirstName(FirstName);

return null; // FIXME return PK value }}

Entity Relationships

Entity relationships are used to model real-world dependencies between business concepts with CMP entity beans. This topics gives an overview of the seven relationship types, and for each of these relationships describes implementation details in the EJBs and the underlying database tables. For more detailed information, see your favorite J2EE documentation.

The topics in this section are:

One-to-One, Unidirectional One-to-One, Bidirectional One-to-Many, Unidirectional One-to-Many, Bidirectional Many-to-One, Unidirectional Many-to-Many, Unidirectional Many-to-Many, Bidirectional

One-to-One, Unidirectional

In a one-to-one unidirectional relationship, object A relates to object B. In addition, given object A you can find a reference to object B, but not the other way around. An example of such a relationship is between a concertgoer and a ticket, assuming the perspective of the ticket counter. Each concertgoer requires exactly one ticket, and the concertgoer will have a reference to his/her ticket. However, given a ticket you don't know the concertgoer. That is, if a lost ticket is returned to the ticket counter, it is not possible to trace it back to the concertgoer.

The Concertgoer EJB will have a CMR field to set and get a reference to a Ticket object. In contrast, there is no reference from the Ticket to the Concertgoer, meaning that there is no direct way to find out if a particular ticket has been assigned to a concertgoer or not and if it has, who the concertgoer

is. (To find this out, you would have to run a query on the Concertgoer EJBs and check each referenced ticket .)

In this particular example, Ticket objects are probably created independently of Concertgoer objects, and the CMR set method is used to associate the Concertgoer with the Ticket. Also, when the concertgoer returns the ticket (and removes himself from the ticket counter database), the Ticket object may not be deleted because it can be resold. When the one-to-one unidirectional relationship is more dependent, as between a Customer and his/her Address, the Customer EJB may have an setAddress business method, which creates a new Address object first, and then uses the CMR set method to set the reference, as is shown in the following code snippet:

public void setAddress(String street, String apt, String city, String state, String zip) throws CreateException { Address currentAddress = this.getAddress( ); if (currentAddress == null) { // Customer's current address not known. newAddress = addressHome.create(street, apt, city, state, zip); setAddress(newAddress); } else { // Update customer's current address. currentAddress.setStreet(street); currentAddress.setApt(apt); currentAddress.setCity(city); currentAddress.setState(state); currentAddress.setZip(zip); } }

Notice that first the CMR get method is used to get the reference to the current address. if the address is not known, a new address object is created after which the reference is set. If there is already a reference to an address, the address object is updated to reflect the new address.

When a customer is removed from the database, the home address can likely be removed as well. To do so, you can specify a cascade delete for this entity relationship, which automatically removes the home address when the customer is removed. For more information, see the @ejbgen:relation Annotation.

With respect to persistent storage of this relationship, one table will have the foreign key column information, that is hold the a copy of the primary key of the other EJB. Typically the Concertgoer table will have an 'Ticket_Index' foreign-key column holding the primary key value of the address (assuming that the Ticket EJB defines only one primary key field; if there are multiple primary key columns, there are multiple foreign key columns holding these values). It is, however, also possible that the Ticket table holds the primary key value of the Concertgoer. Regardless of the implementation in the database table, the EJB container will ensure that the relationship is correctly represented.

One-to-One, Bidirectional

In a one-to-one bidirectional relationship, object A relates to object B and both reference each other. An example of such a relationship is between a concertgoer and a creditcard, again assuming the perspective of the ticket counter. Each concertgoer has only one credit card (to purchase a ticket), and if a credit card is inadvertently left behind at the ticket counter, it can be returned to the owner.

The Concertgoer EJB will have a CMR field to set and get a reference to a CreditCard object. In addition, the CreditCard object will have a CMR field to set and get a reference to a Concertgoer object. Also, the bidirectionality of this relationship is ensured by the EJB container. That is, when you use the Concertgoer's CMR set method to set a reference to a CreditCard object, the CMR field of the

CreditCard object is automatically updated to hold a reference to this Concertgoer. Similarly, when you change or remove a reference in one object, this change is automatically applied to the other object. As far as creating and deleting the object a CMR field references, similar design considerations apply as discussed above for one-to-one unidirectional relationships. With respect to creating a new creditcard for a concertgoer, it is possible that the Concertgoer EJB has a business method setCreditCard, which creates a new creditcard record and then sets the reference, similar to the setAddress method shown above. If on the other hand the CreditCard EJB defines a create method that creates the CreditCard object and sets the reference to the Concertgoer object, the reference must be set in the ejbPostCreate step. An example of this is shown below.

With respect to persistent storage of this relationship, there is again quite some flexibility how this is implemented in the database tables. One of the possibilities is that only the ConcertGoer table has a foreign key column holding the primary key value of a creditcard. There are other possibilities as well. Regardless of the implementation in the database table, the EJB container will ensure that the relationship is correctly represented.

One-to-Many, Unidirectional

In a one-to-many unidirectional relationship, object A relates to many objects B, there are references from object A to all objects B, but not the other way around. An example of such a relationship is between a concertgoer and CDs purchased after the concert. A concertgoer can purchase many CDs, but for a purchased CD, again inadvertently lost and found, it is not possible to trace it back to the concertgoer who made the purchase.

The Concertgoer EJB will have a CMR field to set and get a Collection/Set of references to CD objects. In contrast, there is no CMR field in the CD object. The choice of java.util.Collection versus java.util.Set depends on whether from a design perspective it makes sense to have a collection with potentially duplicate references to the same object, or to have a set without duplicate references.

In this particular example, Concertgoer objects are probably created independently of CD objects, and a new reference is added to the CMR field uses the Collection/Set's add method, while a reference is deleted without deleting the CD object using the Collection/Set's remove method. When the relationship is more dependent, as between a Band and its Recordings, the Band EJB may have an addRecording business method, which creates a new Recording object first, and then adds it to the collection, as is shown in the following code snippet:

public void addRecording(String recording) throws CreateException { Recording album = recordingHome.create(getBandName(), recording); Collection recordings = getRecordings(); if(album != null) { recordings.add(album); } }

Notice that this method first creates the album, then uses the CMR get method to obtain a collection of the current recordings of the band, and then adds the new recording to the collection. Without the last step the recording would be created, but would not be referenced by the band.

When the Band object is deleted from the database, it might or might not make sense to cascade delete its recordings, depending on the real-world scenario you are representing.

With respect to persistent storage of this relationship, the only possible implementation is for the CD table to have a foreign key column holding the primary value of the concertgoer. As you might notice, the model and the actual implementation are reversed; the EJB container again ensures that the relationship is correctly represented.

Note. WebLogic at present doesn't support the use of a join table to implement one-to-many relationships.

One-to-Many, Bidirectional

In a one-to-many bidirectional relationship, object A relates to many objects B, there are references from object A to all objects B, and each object B references object A. An example of such a relationship is between a concertgoer and a creditcard, assuming the perspective of the concertgoer. Each concertgoer can have many credit cards, and if a credit card is inadvertently lost, it can be returned to the owner. Notice that this is the second example of a relationship between a concertgoer and creditcard. Above a one-to-one bidirectional relationship was defined, assuming the perspective of the ticket counter instead of the concertgoer.

Note. Realize that one-to-many bidirectional relationships and many-to-one bidirectional relationships are conceptually identical and are therefore listed as one type of relationship.

The Concertgoer EJB will have a CMR field to set and get a Collection/Set of references to CreditCard objects. The CreditCard object will have a CMR field to set and get a reference to a ConcertGoer object. Again, the bidirectionality of this relationship is ensured by the EJB container. That is, when you set/add the reference to one of the EJBs, the reference is automatically updated for the other EJB. As far as creating and deleting the object a CMR field references, similar design considerations apply as discussed above.

With respect to persistent storage of this relationship, the only possible implementation is for the CreditCard table to have a foreign key column holding the primary value of the concertgoer.

Note. WebLogic at present doesn't support the use of a join table to implement one-to-many relationships.

Many-to-One, Unidirectional

In a many-to-one unidirectional relationship, many objects A relate to one object B, there is a reference from each object A to object B, but not the other way around. An example of such a relationship is between a concert and a venue, assuming the perspective of a concertgoer. There are many different concerts at the same venue but the concertgoer is probably less concerned to know the concerts given the venue. However, if the latter is a business requirement, you will model this as a one-to-many (venue-to-concerts) bidirectional relationship.

The Concert EJB will have a CMR field to set and get a reference to a Venue object. In contrast, the Venue object will not have a CMR field. When a new concert is scheduled, the venue likely needs to be known at this time. In other words, when you create a Concert object, the reference to the Venue object should be set as part of the create procedure, as is shown in the following example:

abstract public class ConcertBean extends GenericEntityBean implements EntityBean{ ...

public Integer ejbCreate(String bandName, Venue theVenue) { setBandName(bandName); return null; }

public void ejbPostCreate(String bandName, Venue theVenue) { setVenue(theVenue); }

...

Notice that ejbCreate sets the name of the performing band, while the reference to the Venue object is set in the corresponding ejbPostCreate method. References must by design always be set in the ejbPostCreate method, because the primary key(s) needed to set the reference may not be available yet until after creation of the object.

Cascade deletions will most likely not make sense for this relationship. That is, removing one concert should not lead to the destruction of the venue, as many other concerts are scheduled for this venue.

With respect to persistent storage of this relationship, the only possible implementation is for the Concert table to have a foreign key column holding the primary value of the venue.

Note. WebLogic at present doesn't support the use of a join table to implement one-to-many relationships.

Many-to-Many, Unidirectional

In a many-to-many unidirectional relationship, object A relates to many objects B, object B relates to many objects A, there are references from each object A to its objects B, but not the other way around. An example of such a relationship is between concertgoers and concerts. A concertgoer will attend many concerts, each concerts will attract many concertgoers, given a concertgoer you might want to know the concerts he/she attended, but given a concert you likely don't want to know the particular concertgoers that were attending it.

The Concertgoers EJB will have a CMR field to set and get a collection/set of references to Concert objects. In contrast, the Concert object will not have a CMR field. As far as manipulating the CMR field, and creating and deleting the objects the CMR field references, similar design considerations apply as discussed above. Cascade deletions typically do not make sense for many-to-many relationships.

With respect to persistent storage of this relationship, a join table is used. Each record in a join table has two foreign-key columns, one holding the primary key value of a concertgoer and the other holding the primary key value of the concert (again assuming that both EJBs are defined to have one unique primary key field).

Many-to-Many, Bidirectional

In a many-to-many bidirectional relationship, object A relates to many objects B, object B relates to many objects A, there are references from each object A to its objects B as well as references from each object B to its objects A. An example of such a relationship is between a passenger and a flight. A passenger can take multiple flights, a flight is typically booked by multiple passengers, given a passenger you want to know the flights, and for a flight you want to know exactly which passengers should be on the airplane.

The Passenger EJB will have a CMR field to set and get a collection/set of references to Flight objects. The Flight EJB will have a CMR field to set and get a collection/set of references to Passenger objects. As far as manipulating the CMR field, and creating and deleting the objects the CMR field references, similar design considerations apply as discussed above. In this particular example it is possible that a passenger books a flight for several passengers at the same time. You can use the Collection/Set's addAll method to add multiple references. Also notice that bidirectionality is again assured by the EJB container, and that cascade deletions typically do not make sense for many-to-many relationships.

With respect to persistent storage of this relationship, a join table is used. Each record in a join table has two foreign-key columns, one holding the primary key value of a concertgoer and the other holding the primary key value of the concert (again assuming that both EJBs are defined to have one unique primary key field).

The Life Cycle of an Entity Bean

The following figure shows the life cycle of an entity bean. An entity bean has the following three states:

Does Not Exist. In this state, the bean instance simply does not exist. Pooled. When WebLogic server is first started, several bean instances are created and placed

in the pool. A bean instance in the pooled state is not tied to particular data, that is, it does not correspond to a record in a database table. Additional bean instances can be added to the pool as needed, and a maximum number of instances can be set

Ready. A bean instance in the ready state is tied to particular data, that is, it represents an instance of an actual business object.

The various state transitions as well as the methods available during the various states are discussed below.

Moving from the Does Not Exist to the Pooled State

When WebLogic server creates a bean instance in the pool, it calls the callback method public void setEntityContext(EntityContext ctx). This method has the parameter javax.ejb.EntityContext, which contains a reference to the entity context, that is, the interface to the EJB container. The entity context contains a number of methods to self-reference the entity bean object, identify the caller of a method, and so forth. Complete details about the javax.ejb.EntityContext can be found in your favorite J2EE documentation and the API reference at http://java.sun.com.

If you want to use the EntityContext reference in the entity bean, you must implement this callback method and store the reference. In addition, this method is also frequently used to look up the home interface of other beans later invoked in one of the bean's methods. The following code sample shows both:

/** * @ejbgen:ejb-local-ref link="Recording" * * ... */abstract public class BandBean extends GenericEntityBean implements EntityBean{ private EntityContext ctx; private RecordingHome recordingHome;

public void setEntityContext(EntityContext c) { // store the reference to the EntityContext ctx = c;

// look up the home interface of the RecordingBean try { javax.naming.Context ic = new InitialContext(); recordingHome = (RecordingHome)ic.lookup("java:/comp/env/ejb/Recording"); } catch(Exception e) { System.out.println("Unable to obtain RecordingHome: " + e.getMessage()); } } 

...

The Pooled State

When a bean instance is in the pooled state, it is not tied to any particular business object. When in the pooled state, the methods defined in the home interface can be invoked, effectively transitioning it from the pooled to the ready state, with the exception of ejbHome methods. When a home method is invoked, a result that is not bean instance specific is returned to the caller, and the bean instance remains in the pooled state. Home methods in turn often invoke ejbSelect methods to query bean instances.

Moving from the Pooled to the Ready State

The following methods move a bean instance from the pooled to the ready state to represent a business object:

ejbCreate and ejbPostCreate. When the create method is invoked on the bean's home interface, the ejbCreate and ejbPostCreate methods are invoked. The bean instance moves to the ready state and represents this newly created business object. After creation, a (local or remote) reference to this object is returned to the caller, enabling the caller to invoke business methods on this instance. The ejbPostCreate method is used to set references to other entity beans as part of the creation of a new bean instance.

findByPrimaryKey. When this method is invoked on the bean's home interface with the (compound) primary key as the parameter, the bean instance moves to the ready state and represents the business object uniquely identified by the parameter. Also a (local or remote) reference to this object is returned to the caller, enabling the caller to invoke business methods on this instance.

Finder methods. When a Finder method is invoked on the bean's home interface, one or a set of references to objects matching the queries are returned to the caller. In many cases the corresponding bean instance(s) are not loaded with data and move to the ready state until at a later point when a business method is actually invoked on this object, a concept known as lazy loading. However, you can specify eager loading, that is, tell the EJB container to load (part of) the data and move the entity bean instance(s) to the ready state as a part of the finder method execution.

The Ready State

When a bean instance is in the ready state, it represent data for a business object. At this point any business method, that is any component method and accessor method, can be invoked on this object. (A component method may in turn call an ejbSelect method.) After a business method executes, the bean returns to the ready state to allow another business method invocation.

From the perspective of the EJB container, the execution of a component method is sandwiched between two synchronization steps:

1. Before a business method is executed, the EJB container updates the fields of the bean instance with the latest data from the database table to ensure that the bean instance has the latest data. Just after the data is updated, the EJB container invokes the callback method ejbLoad. If your entity bean needs to execute some custom logic as part of this synchronization step, you can use implement it using this callback method.

2. The business method executes and completes. 3. The EJB container now updates the database table to ensure that it contains the latest data

from the entity bean instance. In other words, if the business method changes data values, this synchronization step ensures these changes are stored. Just prior to updating the database table, the EJB container invokes the callback method ejbStore. If your entity bean needs to execute some custom logic as part of this synchronization step, you can implement it using this callback method.

Because a record in a database table can be accessed by multiple bean instances at the same time, these synchronization steps ensure that each bean instance always has the latest data. However, in some cases these synchronization steps might be overkill and unnecessarily slow down performance. For instance, an entity bean might be read-only, reading data that is changed rarely if at all. In these cases one can safely bypass the synchronization steps without risking violations to data integrity.

Moving from the Ready to the Pooled State

When a caller invokes a remove method to delete an entity bean instance and its underlying record in the database table, the EJB container will delete the bean instance. Just prior to deleting the instance, it will call the callback method ejbRemove. If your entity bean needs to execute some custom logic prior to deletion, you can implement it using this callback method. After the data is deleted, the bean instance returns to the pooled state. The bean instance is no longer tied to any particular business object, and can be used to execute a home method or one of the methods that will tie it to a new set of data and move it to the ready state.

Activation and Passivation

To more optimally manage resources, the EJB container might passivate a bean instance by moving it from the ready state to the pooled state. During passivation the entity bean instance is dissociated from the business object it represents, and become available to represent another set of data. Conversely, a passivated bean might be activated, meaning that it moves from the pooled to ready state to represent a business object.

It should be noted that the caller (a client application or another EJB) of the entity bean instance will be unaware of passivation having taken place. The caller's reference to the entity bean instance is still maintained and valid; that is, if the caller subsequently invokes a business method on this entity bean instance, an instance from the pooled state will be moved to the ready state to represent this business object.

A bean instance can be passivated when none of its business method are invoked. Passivation occurs after synchronization has completed, guaranteeing that the database has stored any changes to the

business object. Just prior to actual passivation, the callback method ejbPassivate is invoked. If your entity bean needs to execute some custom logic prior to passivation, you can implement it using this callback method.

When a previously passivated bean instance is activated to service business method invocation, the callback method ejbActivate is invoked. If your entity bean needs to execute some custom logic prior to activation, you can implement it using this callback method. For instance, you might use this callback method to reinitialize values of nonpersistent fields, that is, fields not stored in the database. After the callback method executes and completes, the synchronization - business method invocation - synchronization procedure described above follows as during any other business method invocation; that is, first synchronization happens during which the latest bean instance is updated with the latest data of the database, followed by the invocation of the ejbLoad callback method. After this completes the business method is invoked, and when this completes, the second synchronization happens during which the ejbStore callback method is invoked and the latest bean instance data is stored to the database.

Moving from the Pooled to the Does Not Exist State

To more optimally manage resources, or when WebLogic server shuts down, the EJB container might remove a bean instance from the pooled state to the does not exist state, allowing it to be garbage collected. Just prior to its destruction, the callback method unsetEntityContext is invoked. If your entity bean needs to execute some cleanup prior to garbage collection, you can implement it using this callback method.

Bean-Managed Persistence

When you use container-managed persistence (CMP) for entity beans, the EJB container handles the interaction with the underlying database. The EJB container ensures synchronization of data just prior and just after a business method executes , it deletes the underlying database record when the entity bean instance is deleted, for an ejbCreate method it inserts the data in the database, it automatically generates the findByPrimaryKey method and handles the database query to find a database record, and it interprets EJB QL and WebLogic QL queries on finder and select methods to generate the corresponding database queries. In most cases entity bean development is done using CMP.

In contrast, when you use bean-managed persistence (BMP) for entity beans, the EJB container will still provide a numbers of services (such as transaction management) but leaves the persistence management up to the bean class. Bean-managed persistence might be necessary when your bean represents an unusual set of data and/or interacts with a legacy system for data storage. The current topic introduces some of the main difference between CMP and BMP, and some of the main differences developing CMP entity beans in WebLogic. For detailed information on CMP bean development, see your favorite J2EE documentation.

Main Differences Between CMP and BMP

Compared to CMP, when you develop BMP entity beans you must take into account the following:

You are responsible for synchronizing the entity bean instance and the underlying database record before and after a business method invocation. To do so you must implement the callback methods ejbLoad and ejbStore. (The EJB container invokes the various callback methods for CMP and BMP entity beans alike.)

The ejbCreate method(s) must take care of storing the new data in the database. The findByPrimaryKey method must be explicitly defined and must take care of locating the

data corresponding to the (compound) primary key in the database. Removing the data from the database when a bean instance is removed must be handled by

the bean class. To do so you must implement the ejbRemove callback method. Query methods cannot be implemented using EJB QL or WebLogic QL. Instead the finder or

select method(s) must define the database queries.

BMP Implementation

When you define a CMP entity bean in WebLogic, you should take into account the following:

To create a new BMP entity bean file, the first step is creating it as you would a CMP entity bean. When the file is created and opened, go to source view and add persistence-type="bmp" to the @ejbgen:entity tag. When you close and re-open the file, you will notice that design view is no longer available and, correspondingly, that the various wizards to for instance add an entity relation or a create method are no longer available.

You need to add an @ejbgen:resource-ref tag to the datasource (the database). Because the EJB container doesn't handle persistence, you should remove the attributes data-source-name and table-name from the @ejbgen:entity tag.

The database table for the BMP entity bean is not created for you by WebLogic. You must define the table in the database.

You must define the property fields and accessor methods. You must define the findByPrimaryKey method and the various callback methods as mentioned

in the previous section. WebLogic will still generate the various interfaces for you. To that effect, you also still use the

appropriate @ejbgen tags to ensure that a particular method is added to the appropriate interface. The findByPrimaryKey method will automatically be added to the defined home interface(s).

What are Session Beans?

Session beans are used to execute business tasks for a client on the server. A session bean typically implements a certain kind of activity, such as ordering products or signing up for courses, and in executing the business rules typically invokes entity beans. For instance, ordering products is likely to involve stored information about products, customers, and credit cards, while signing up for courses is likely going to require invoking entity beans representing students and courses.

Stateful and Stateless

There are two types of session beans, stateful and stateless. A stateful session bean maintains conversational state. In other words, a stateful session bean remembers the calling client application from one method to the next. For a stateful session bean, the results produced by one method might be co-dependent on the results of its prior methods invoked by the same client. A stateful session bean maintains this conversation with the client until the conversation times out or the client explicitly ends the conversation by invoking the bean's remove method.

In contrast, a stateless session bean does not maintain any conversational state, that is, it does not remember which client invoked one of its methods, and does not maintain an internal state between methods. Each session bean method is independent, and the only client input is the data passed in its parameters.

Stateful session beans are tied to a particular client for the duration of the conversation, while stateless session beans are only tied to a particular client for the duration of a method execution. After method execution completes, a stateless session bean is ready to serve another client application. Consequently, a small number of stateless session beans can be used to serve a large number of client applications. Stateless session beans tend to be more commonly preferred over stateful session beans for this reason. When the client application is a page flow or a conversational web service, conversational state is remembered by the client application itself, making it possible to use a stateless session bean while maintaining a continuous session with the user of the client application. When you develop a new session bean in WebLogic, by default a stateless session bean is defined.

Home and Business Interfaces

Like an entity bean, a session bean can have four different interfaces, called the local home interface, the local business interface (or simply, the local interface), the remote home interface, and the remote business interface (or simply, the remote interface). The local interfaces define the bean's methods that can be used by other EJBs, EJB controls, web services and page flows defined within the same application. That is, if you define a session bean and only plan to use it within that application, you can use local interfaces. In contrast, the remote interfaces define the bean's methods that be invoked by EJBs, EJB controls, web services and page flows defined in other applications.

To determine what interfaces are defined for a session bean, ensure you are in Design View and go to the Naming section in the Property Editor. The Remote EJB and Local EJB sections refer to the remote and local interfaces; within each section the Home class name refers to the home interface, and the Bean class name refers to the business interface. In Source View, the attributes are part of the @ejbgen:file-generation Annotation. When you define a new session bean, by default only the remote interfaces are defined.

A session bean's (remote or local) home interface contains the create methods used to obtain a reference to the bean instance. Its (remote or local) business interface contains the component methods that are used to encapsulate a particular piece of business logic.

The Create Methods

For a stateless session bean, you must define exactly one ejbCreate() method with no parameters. This method must be invoked to obtain to a reference to a session bean instance. Once you have obtained a reference, you can invoke the session bean's component methods. If you call a stateless session bean via an EJB control, you do not need to call the create method explicitly; the EJB control will create a reference for you when you call a component method.

A stateful session bean must have at least one ejbCreate method and, like entity beans, can have multiple ejbCreate methods. One of these methods must be invoked to obtain a reference to the session bean instance before you can invoke the session bean's component methods. If you call a stateful session bean via an EJB control, you must first call (one of) its create methods to obtain a reference.

Unlike with stateless session beans, when you can call a stateful session bean's create method to obtain a reference and subsequently invoke several component methods, each method is guaranteed to be handled by the same bean instance on the server. For more information, see The Life Cycle of a Session Bean.

Component Methods

Component methods are the business methods that are invoked on a session bean instance. A simple example of a business method is reserveTickets(customer, movieName, date), which is used to reserve tickets for a movie. For more information, see How Do I: Add a Component Method to an Entity or Session Bean?

In principle there is no difference between component methods for a stateful and a stateless session bean. However, the component methods of a stateless session bean must be passed all the necessary data to execute business logic as parameters, while this is not necessary for the component methods of a stateful session bean. For instance, for a stateful session bean the component method reserveTickets() can be used to make ticket reservations for a movie, after the component method setCustomer(customer) is called to set the customer data, setMovie(name) is called to make the movie selection, and setDate(date) is called to set the movie time. For a stateless session bean, these parameters must be passed to the component method making the actual reservations, as in reserveTickets(customer, movieName, date).

Other Methods

A session bean has several predefined methods, as well as a number of callback methods, invoked by the EJB container during certain operations, that a session bean must implement. In WebLogic these callback methods are by default automatically implemented. In many cases you will find it unnecessary to use these methods. To learn more about these methods, see Defining a Session Bean and The Life Cycle of a Session Bean.

Creating a Session Bean

To create a session bean, you can choose one of the following methods:

Create a session bean from scratch. If you are designing a new session bean in EJB project, you can define a new session bean. To find out exactly how to do this, see How Do I: Create an Enterprise JavaBean? When you create a new session bean, by default the remote interfaces and various other defaults are defined. For more details, see @ejbgen:file-generation Annotation.

Import a session bean. If you have developed session beans in another development environment, you can import these into WebLogic. To import an EJB, you need the EJB Jar file as well as the source files. You can import multiple EJBs at the same time. For more information, see How Do I: Import an Enterprise JavaBean? After you have imported a session bean, you can enhance its definition.

Note. If you have existing session beans that you plan to invoke in the application, for instance via another EJB or an EJB control, but you do not intend to change their definitions, you can suffice by adding the EJB Jar to the application. For more information, see How Do I: Add an Existing Enterprise JavaBean to an Application?

Defining a Basic Session Bean The following figure shows the design view of a basic session bean called PriceCheckerBean:

This stateless session bean's component method receives the name of a product and returns the price when known, or a 'product unknown' message if the product cannot be found. It uses the ProductBean, shown in Defining an Entity Bean, to look up a product in the database and return its price. The source code of the PriceChecker bean is given below:

package myBeans;

import javax.ejb.*;import javax.naming.InitialContext;import javax.naming.NamingException;import weblogic.ejb.*;

/** * @ejbgen:session

* ejb-name = "PriceChecker" * * @ejbgen:jndi-name local="ejb.PriceCheckerLocalHome" * * @ejbgen:file-generation remote-class="false" remote-home="false" local-class="true" * local-class-name = "PriceCheckerLocal" local-home="true" local-home-name = "PriceCheckerLocalHome" * * @ejbgen:ejb-local-ref link="Product" */public class PriceCheckerBean extends GenericSessionBean implements SessionBean{ private ProductHome productHome; public void ejbCreate() { try { javax.naming.Context ic = new InitialContext(); productHome = (ProductHome)ic.lookup("java:comp/env/ejb/Product"); } catch (NamingException ne) { throw new EJBException(ne); } }

/** * @ejbgen:local-method */ public String returnPrice(String product) { Product theProduct; int visitNumber;

try { theProduct = productHome.findByPrimaryKey(product); } catch(FinderException fe) { return "Product not known"; } return "The price of this product is " + theProduct.getPrice(); }}

The @ejbgen:session annotation contains the actual name of the session bean. For stateful session beans this tag will contain the attribute type="Stateful". In the ejbCreate method a reference to the Product entity bean's local home interface is obtained. The JNDI reference Product used in the lookup method to look up the Product bean, is mapped to this bean's local interface using an @ejbgen:ejb-local-ref Annotation, which is defined at the top of the PriceChecker bean class definition. To learn more about JNDI naming, consult your favorite J2EE documentation or go to http://java.sun.com.

The method returnPrice implements the business logic for this class. It finds a particular product using the Product bean and returns its price. If the product cannot be found in the database, it returns a Product not known message instead.

In WebLogic, all the information needed to make a session bean are stored in a single file, instead of separate JAVA files for the bean class, the local business interface, the local home interface, and so forth. When you build a session bean, these classes are auto-generated. Various ejbgen annotations are used to hold the information required to make this generation possible. Specifically, the @ejbgen:file-generation annotation specifies the names of the local home and business interface for the PriceChecker bean, and the @ejbgen:local-method annotation on the component method specifies that the method should be defined in the local business interface. To verify that these JAVA and

corresponding CLASS files are generated, expand the JAR file created during a build (located in the Modules folder in the Application pane), and locate and open the generated files in the folder reflecting the package name. For the PriceCheckerBean, the PriceCheckerBean.java (bean definition), PriceCheckerLocal.java (local interface definition), and PriceCheckerLocalHome.java (local home interface definition) files are auto-generated.

Predefined and Callback Methods

The interfaces of session (and entity) beans extend a particular interface which contains various useful methods. Specifically:

The local interface extends javax.ejb.EJBLocalObject The local home interface extends javax.ejb.EJBLocalHome The remote interface extends javax.ejb.EJBObject The remote home interface extends javax.ejb.EJBHome

For example, the interfaces contain a remove method to remove a bean instance and, for a stateful session bean, end the conversation. Complete details about these interfaces and the methods they define can be found in your favorite J2EE documentation and the API reference at http://java.sun.com.

Every session bean must implement the javax.ejb.SessionBean interface. This interface defines callback methods that are called by the EJB container at specific times. The callback methods are setSessionContext, ejbActivate, ejbPassivate, and ejbRemove. When you define a session bean from scratch, it will extend weblogic.ejb.GenericSessionBean, which contains empty implementations of these callback methods. In other words, you will only need to define these methods if you need to override the empty implementation. If you import a session bean, these callback methods will probably be implemented directly in the bean's ejb file. For more details about the callback methods and their role in the interaction between the session bean and the EJB container, see The Life Cycle of a Session Bean.

The Life Cycle of a Stateless Session Bean

The following figure shows the life cycle of a stateless session bean. A stateless session bean has two states:

Does Not Exist. In this state, the bean instance simply does not exist. Ready. When WebLogic server is first started, several bean instances are created and placed

in the Ready pool. More instances might be created by the container as needed by the EJB container.

The various state transitions as well as the methods available during the various states are discussed below.

Moving from the Does Not Exist to the Ready State

When the EJB container creates a stateless session bean instance to be placed in the ready pool, it calls the callback method public void setSessionContext(SessionContext ctx). This method has the parameter javax.ejb.SessionContext, which contains a reference to the session context, that is, the interface to the EJB container, and can be used to self-reference the session bean object. Complete details about the javax.ejb.SessionContext can be found in your favorite J2EE documentation and the API reference at http://java.sun.com.

After the callback method setSessionContext is called, the EJB container calls the callback method ejbCreate. You can implement this callback method to for instance obtain the home interfaces of other EJBs invoked by the session bean, as shown in Defining a Session Bean. The ejbCreate method is only called once during the lifetime of a session bean, and is not tied to the calling of the create method by a client application. For a stateless session bean, calling the create method returns a reference to a bean instance already in the ready pool; it does not create a new bean instance. The management of stateless session bean instances is fully done by the EJB container.

The Ready State

When a bean instance is in the ready state, it can service client request, that is, execute component methods. When a client invokes a business method, the EJB container assign an available bean instance to execute the business method. Once executed, the session bean instance is ready to execute another business method.

Moving from the Ready to the Does Not Exist State

When the EJB container decides to reduce the number of session bean instances in the ready pool, it makes the bean instance ready for garbage collection. Just prior to doing this, it calls the callback method ejbRemove. If your session bean needs to execute some cleanup action prior to garbage collection, you can implement it using this callback method. The callback method is not tied to the remove method invoked by a client. For a stateless session bean, calling the remove method invalidates the reference to the bean instance already in the ready pool, but it does not move a bean instance from the ready to the does not exist state, as the management of stateless session bean instances is fully done by the EJB container.

The Life Cycle of a Stateful Session Bean

The following figure shows the life cycle of a stateful session bean. It has the following states:

Does Not Exist. In this state, the bean instance simply does not exist. Ready. A bean instance in the ready state is tied to particular client and engaged in a

conversation. Passive. A bean instance in the passive state is passivated to conserve resource.

The various state transitions as well as the methods available during the various states are discussed below.

Moving from the Does Not Exist to the Ready State

When a client invokes a create method on a stateful session bean, the EJB container creates a new instance and invokes the callback method public void setSessionContext(SessionContext ctx). This method has the parameter javax.ejb.SessionContext, which contains a reference to the session context, that is, the interface to the EJB container, and can be used to self-reference the session bean object. Complete details about the javax.ejb.SessionContext can be found in your favorite J2EE documentation and the API reference at http://java.sun.com. After the callback method setSessionContext is called, the EJB container calls the callback method ejbCreate that matches the signature of the create method.

The Ready State

A stateful bean instance in the ready state is tied to a particular client for the duration of their conversation. During this conversation the instance can the execute component methods invoked by the client.

Activation and Passivation

To more optimally manage resources, the EJB container might passivate an inactive stateful session bean instance by moving it from the ready state to the passive state. When a session bean instance is passivated, its (non-transient) data is serialized and written to disk, after which the the bean instance is purged from memory. Just prior to serialization, the callback method ejbPassivate is invoked. If your session bean needs to execute some custom logic prior to passivation, you can implement it using this callback method.

If after passivation a client application continues the conversation by invoking a business method, the passivated bean instance is reactivated; its data stored on disk is used to restore the bean instance state. Right after the state has been restored, the callback method ejbActivate is invoked. If your session bean needs to execute some custom logic after activation, you can implement it using this callback method.The caller (a client application or another EJB) of the session bean instance will be unaware of passivation (and reactivation) having taken place.

If a stateful session bean is set up to use the NRU (not recently used) cache-type algorithm, the session bean can time out while in passivated state. When this happens, it moves to the does not exist state, that is, it is removed. Prior to removal the EJB container will call the callback method ejbRemove. If a stateful session bean is set up to use the LRU (least recently used) algorithm, it cannot time out while in passivated state. Instead this session bean is always moved from the ready state to the passivated state when it times out.

The exact timeout can be set using the idle-timeout-seconds attribute on the @ejbgen:session annotation. The cache-type algorithm can be set using the cache-type attribute on the same annotation.

Moving from the Ready to the Does Not Exist State

When a client application invokes a remove method on the stateful session bean, it terminates the conversation and tells the EJB container to remove the instance. Just prior to deleting the instance, the EJB container will call the callback method ejbRemove. If your session bean needs to execute some custom logic prior to deletion, you can implement it using this callback method.

An inactive stateful session bean that is set up to use the NRU (not recently used) cache-type algorithm can time out, which moves it to the does not exist state, that is, it is removed. Prior to removal the EJB container will call the callback method ejbRemove. If a stateful session bean set up to use the LRU (least recently used) algorithm times out, it always moves to the passivated state, and is not removed.

The exact timeout can be set using the idle-timeout-seconds attribute on the @ejbgen:session annotation. The cache-type algorithm can be set using the cache-type attribute on the same annotation.

Developing Message-Driven Beans

An message-driven EJB is used to receive and process asynchronous messages using JMS. Message-driven EJBs are never directly invoked by other EJBs. However, they in turn can invoke methods of session and entity beans and send JMS messages to be processed by other message-driven EJBs. The topics listed below discuss development of message-driven beans.

What are Message-Driven Beans?

Message-driven beans are server-side objects used only to process JMS messages. These beans are stateless, in that each method invocation is independent from the next. Unlike session and entity beans, message-driven beans are not invoked by other beans or client applications. Instead a message-driven bean responds to a JMS message.

Because message-driven beans are not invoked by other EJBs or clients, these beans do not have interfaces. For each message-driven bean a single method, onMessage, is defined to process a JMS message. Although message-driven beans cannot be invoked by other EJBs, they can in turn invoke other EJBs. Also, message-driven beans can send JMS messages. As with the other types of EJBs, the EJB container is responsible for managing the beans environment, including making enough instances available for processing and message-acknowledgement.

Asynchronous and Concurrent Processing

A core feature of message-driven beans is the notion of asynchronous processing. A client application can send a JMS message to execute a certain business task. After the message has been sent, the client application can continue right away and does not have to wait for the JMS message to be received and processed. This is especially helpful when the business task is complex, requires the use of entity (and session) beans, and takes a long time to complete. In contrast, if the same client application were to use a session bean to execute a certain business task, it would have to wait until the session bean method completed and returned control to the client application. The message façade design pattern formalizes this use of message-driven beans as an intermediary between client applications and entity beans to achieve asynchrony. An example of this pattern is shown in the Message-Driven Bean Sample.

Another important feature of message-driven beans is that JMS messages are processed concurrently. That is, although each bean instance handles a message at a time, the EJB container takes care of creating enough bean instances to handle the message load at a given moment. In WebLogic you can set the initial number and max number of bean instances created by the container. For more information, see the @ejbgen:message-driven Annotation.

Because message-driven beans are stateless and processing of JMS messages occurs in an asynchronous message, there is no guarantee that messages are processed in the order they were sent. Therefore, sending multiple messages such that one message is dependent on the successful processing of another message might cause unexpected results. Instead, you should reconsider the granularity of your business task such that one message can initiate its execution, possibly by handling one piece of the task, and then sending a JMS message to be processed by another message-driven bean for the remainder of the business task.

Topics and Queues

A message-driven bean listens to a particular channel for JMS messages. There are two types of channels, namely topics and queues. Topics implement the publish-and-subscribe messaging model, in which a given message can be received by many different subscribers, that is, many different message-driven bean classes (not instances) listening to the same topic. In contrast, queues implement the point-to-point messaging model, in which a given message is received by exactly one message-driven bean class, even when multiple classes are listening to this queue.

The Life Cycle of a Message-Driven Bean

The EJB container is responsible for creating a pool of message-driven bean instances. When it creates an instance, it calls the setMessageDrivenContext() and the ejbCreate() methods. At this point the message-driven bean is ready to receive messages. When a bean instance is processing a JMS message, its onMessage method is being invoked. When the EJB container removes a bean instance, it first calls the ejbRemove method before the instance is ready for garbage collection. The life cycle of a message-driven bean is depicted in the following figure.

When defining a message-driven bean in WebLogic, in most cases you will implement the onMessage method to execute a particular business task, and use the ejbCreate method to implement actions that only need to be executed once, such as looking up the home interfaces of entity beans that are invoked by the message-driven bean's onMessage method. A typical example of simple message-driven bean is given below. Notice that the ejbCreate method is used to find the home interface of a Recording entity bean, while the onMessage method processes the message and invokes the Recording bean:

/** * @ejbgen:message-driven * ejb-name = Statistics * destination-jndi-name="jms.EJBTutorialSampleJmsQ" * destination-type = javax.jms.Queue * * @ejbgen:ejb-local-ref

* type="Entity" * name="ejb/recordLink" * local="bands.Recording" * link="Recording" * home="bands.RecordingHome" */public class StatisticsBean extends GenericMessageDrivenBean implements MessageDrivenBean, MessageListener{ private RecordingHome recordingHome;

public void ejbCreate() { try { javax.naming.Context ic = new InitialContext(); recordingHome = (RecordingHome)ic.lookup("java:/comp/env/ejb/recordLink"); } catch(NamingException ne) { System.out.println("Encountered the following naming exception: " + ne.getMessage()); } } public void onMessage(Message msg) { try { // read the message MapMessage recordingMsg = (MapMessage)msg; String bandName = recordingMsg.getString("bandName"); String recordingTitle = recordingMsg.getString("recordingTitle"); ... // save the rating with the recording Recording album = recordingHome.findByPrimaryKey(new RecordingBeanPK(bandName, recordingTitle)); album.setRating(rating); } catch(Exception e) { System.out.println("Encountered the following exception: " + e.getMessage()); } }}

You can implement the ejbRemove method if cleanup is required before the object is removed, and you can implement setMessageDrivenContext method if you need access to the javax.ejb.MessageDrivenContext provided by the EJB container. The MessageDrivenContext contains information about the container, in particular its transaction methods; for more information, see your favorite J2EE documentation. A message-driven bean defined in WebLogic by default extends weblogic.ejb.GenericMessageDrivenBean, which provides empty definitions for all these methods with the exception of the onMessage method; the definition of your bean must therefore implement the onMessage method.

 Using a JMS Control

In WebLogic you can use a JMS control to send JMS messages to a topic or queue. JMS controls can be used to send messages in page flows and web services; they cannot be used to send JMS messages in EJBs. You can use JMS controls to both send and receive messages. In this case you will only be using the JMS control to send messages, as a message-driven bean will be used to process received messages. For details on how to create JMS controls for topics and queues, see JMS Control.

The advantage of using a JMS control is that the details of the JMS messaging API are by and large taken care of by the JMS control. For example, the following code samples shows the definition of a JMS control to send messages to a queue:

/** * @jc:jms send-type="queue" send-jndi-name="jms.SamplesAppMDBQ" * connection-factory-jndi-name="weblogic.jws.jms.QueueConnectionFactory" */public interface sendToQueueControl extends JMSControl, com.bea.control.ControlExtension { /** * this method will send a javax.jms.Message to send-jndi-name */ public void sendJMSMessage(Message msg); static final long serialVersionUID = 1L;}

As the definition shows, you must still define the name of the queue to which to send the JMS message as well as the name of a QueueConnectionFactory. However, to send a message using this JMS control, you simply need to invoke the method sendJMSMessage and pass a message as the parameter. The JMS control handles the creation of a factory instance, a connection, session, and so forth.

When using a JMS control from a page flow or web service, you can use a built-in control to encapsulate all the message sending related logic, instead of defining this directly in the page flow or web service. For instance, the following built-in control code snippet uses the JMS control defined above to send 20 messages at one time to a queue.

...public class MessageSenderImpl implements MessageSender, ControlSource{ /** * @common:control */ private messageDriven.sendToQueueControl queueSend;

/** * @common:operation * @common:message-buffer enable="true" */ public void add20ViaQueue(int currentNum) throws JMSException { String name; for(int i = 0; i < 20; i++) { MapMessage msg = queueSend.getSession().createMapMessage(); msg.setStringProperty("Command", "Add"); name = Integer.toString(currentNum + i); msg.setString("tokenName", name); queueSend.sendJMSMessage(msg); } }}

For more information on built-in controls, see Building Custom Java Controls. The use of JMS controls and built-in controls in a page flow is demonstrated in the Message-Driven Bean Sample.

Sending Messages from EJBs

To send JMS message from an EJB, you cannot use JMS controls and must use the 'standard' JMS messaging API. (You can also use the standard messaging API in page flows and web services if you do not want to use a JMS control.) The following code sample shows a session bean sending a message to a queue. The queue and QueueConnectionFactory are defined using @ejbgen:resource-env-ref and @ejbgen:resource-ref annotations. In the bean's ejbCreate method the queue and QueueConnectionFactory are located (this only need to be done once), while the method executeTask

contains the correct procedure to create a connect, session, sender, and message before sending the JMS message.

/**

* @ejbgen:resource-ref * auth="Container" * jndi-name = "weblogic.jws.jms.QueueConnectionFactory" * name = "jms/QueueConnectionFactory" * type="javax.jms.QueueConnectionFactory" * * @ejbgen:resource-env-ref * jndi-name="jms.ASampleJmsQ" * name="jms/ASampleJmsQ" * type = "javax.jms.Queue" * * ... */public class ASessionBean extends GenericSessionBean implements SessionBean{ private QueueConnectionFactory factory; private Queue queue; public void ejbCreate() { try { javax.naming.Context ic = new InitialContext(); factory = (QueueConnectionFactory) ic.lookup("java:comp/env/jms/QueueConnectionFactory"); queue = (Queue) ic.lookup("java:comp/env/jms/ASampleJmsQ"); } catch (NamingException ne) { throw new EJBException(ne); } }

/** * @ejbgen:local-method */ public void executeTask(String prop1, String prop2) { try { //interpret the properties ... //send a message QueueConnection connect = factory.createQueueConnection(); QueueSession session = connect.createQueueSession(true,Session.AUTO_ACKNOWLEDGE); QueueSender sender = session.createSender(queue); MapMessage recordingMsg = session.createMapMessage(); recordingMsg.setString("Property1", prop1); recordingMsg.setString("Property2", prop2); sender.send(recordingMsg); connect.close(); } catch(JMSException ne) { throw new EJBException(ne); } }}

JMS Message Types

The JMS messaging API defines various message types, allowing for different types of information to be included in the body of a JMS message. Frequently used message types are TextMessage to send a text string, MapMessage to create sets of name-value pairs, and ObjectMessage to send a serializable object. For more details on the various message types, see your favorite J2EE documentation or the javax.jms.Message API documentation at http://java.sun.com.

Message Selectors

A JMS message can also contain message properties. There are different types of properties which can serve a number of functions. One common use of a message property is to set a message selector. A message selector is a property that is used by a message-driven bean to determine whether it should process this message or should leave its processing up to another message-driven bean listening to the same topic or queue.

The following example shows how to set a String property that will act as a message selector for a JMS MapMessage:

Message msg = session.createMapMessage();msg.setStringProperty("MyMessage", "Build 126"");

A message-driven bean that is defined to specifically process this type of message will include a message selector property:

* @ejbgen:message-driven * message-selector="MyMessage = 'Build126'" * ejb-name = MDBean * ... */public class MDBean extends GenericMessageDrivenBean implements MessageDrivenBean, MessageListener{ ...

In other words, this bean will respond specifically to this type of message and will leave the processing of other messages up to other beans listening to this topic or queue. By using a message selector you can send different types of messages to the same channel instead of having to create a separate queue/topic for every type of message. For more details on the various message properties, see your favorite J2EE documentation or the javax.jms.Message API documentation at http://java.sun.com.

 Processing JMS Messages

When a JMS message is sent to a topic or queue, a message-driven bean instance will interpret and process the message, as specified in its onMessage method. When a JMS message is sent to a topic, a publish-and-subscribe system, an instance of every message-driven bean class listening to this topic will in principle receive and process this message. However, if the message contains a message selector, only the message-driven bean(s) matching the message selector will process the message. When a JMS message is sent to a queue, a point-to-point system, only one message-driven bean will process the message, even when multiple bean classes are listening to the queue. Again, the use of a message selector might limit the bean processing the message. For more on message selectors, .

How the JMS message is processed fully depends on the business task that is being modeled. It might range from simply logging the message to executing a range of different tasks which include invoking methods on session and entity beans, or sending JMS messages to be processed by other message-driven beans. The following code sample shows one use of a message-driven bean. This bean responds only to JMS messages delivered via the jms/SamplesAppMDBQ queue and contain the message selector Command= 'Delete'. When processing a JMS message, an instance of this bean invokes the query method findAll of the entity bean SimpleToken, and subsequently deletes all SimpleToken records from the underlying database.

/**

* @ejbgen:message-driven * message-selector="Command = 'Delete'" * ejb-name = DeleteViaQMD * destination-jndi-name = jms/SamplesAppMDBQ * destination-type = javax.jms.Queue * * @ejbgen:ejb-local-ref link="SimpleToken" */public class DeleteViaQMDBean extends GenericMessageDrivenBean implements MessageDrivenBean, MessageListener{ private SimpleTokenHome tokenHome; public void ejbCreate() { try { javax.naming.Context ic = new InitialContext(); tokenHome = (SimpleTokenHome)ic.lookup("java:/comp/env/ejb/SimpleToken"); } catch(NamingException ne) { System.out.println("Encountered the following naming exception: " + ne.getMessage()); } }

public void onMessage(Message msg) { try { Iterator allIter = tokenHome.findAll().iterator(); while(allIter.hasNext()) { ((SimpleToken) allIter.next()).remove(); } } catch(Exception e) { System.out.println("Encountered the following exception: " + e.getMessage()); } }} 

Acknowledgement and Transactions

When a message-driven bean instance receives a message, and it is not part of a container-managed transaction, by default it immediately sends an acknowledgement to the JMS provider notifying that the message has been received. This will prevent the JMS provider from attempting to redeliver it. However, the acknowledgement only indicates that a message has been successfully received, but it does not guarantee that the message is successfully processed. For instance, a system exception might occur when attempting to locate an entity bean or update its records, causing the processing to fail.

If you want to ensure that a message is redelivered when processing fails, you can make the message-driven bean be part of a transaction. The easiest approach is to use container-managed transaction, where the EJB container is responsible for transaction management. To enable container-managed transaction for a message-driven bean, make sure that your cursor is placed inside the ejbgen:message-driven tag and use the Property Editor to set the transaction-type to Container and the default-transaction to Required. When JMS message processing executes successfully, any changes made during this business task, such as update to entity bean records, are committed and acknowledgement is sent to the JMS provider. However, when JMS message processing fails due to a system exception, any changes are rolled back and receipt is not acknowledged. In other words, after processing fails, the JMS provider will attempt to resend the JMS message until processing is

successfully or until the maximum number of redelivery attempts specified for this topic or queue has been reached.

Note. When a message-driven bean is part of a transaction, it executes as part of its own transaction. In other words, if the transaction fails, changes that were made as part of the onMessage method are rolled back, but the occurrence of an exception has no direct effect on the EJB or client application sending the JMS message, as the sender and the message-driven bean are decoupled.

To learn more about container-managed transactions, see EJBs and Transactions. To learn more about bean-managed transaction (that is, explicit transaction management), please refer to your favorite J2EE documentation.

WebLogic Workshop Security Overview

The following overview sets out the aims of security and the security technologies available in WebLogic Workshop.

Security Goals

All security technologies are designed to achieve three basic goals.

1. Authentication of participants

When a participant is authenticated it means that there is some assurance that the participant really is who they say they are. Different scenarios call for different levels of authentication. In some cases, only the web resource needs to be authenticated, while the client can remain anonymous. For example, if your web resource takes customer credit card numbers, you want your customers to have peace of mind that they are providing their card numbers to you, and not some malicious third party. But your customers may remain anonymous. In other cases, the web resource will want proof of identity from its clients. For example, if a bank provided online access to its customer's checking accounts, the bank should require some form of client authentication from those parties who want to access the online accounts.

2. Confidential communication

Data transmission is confidential when only the intended recipient can read the data. 3. Integrity of transmitted data

Data integrity means that the data has not been altered in the process of transmission. (When using transport security, there is generally no need to take special measures to ensure data integrity. This is because the encryption processes used by SSL ensures data integrity.)

The topics below provide detailed information to help you implement a security strategy for your WebLogic Workshop application.

WebLogic Workshop Security Technologies

WebLogic Workshop offers three main areas of security technology:

transport security web service security role-based security

Transport security refers to the mechanisms used to enable the http protocol to operate over a secure transport connection. Transport security lets you secure your web resources through SSL, username/password authentication, and client digital certificates.

An advantage of transport security is that is well known and relatively easy to implement. A disadvantage is that data is secured only while it is in transport over the wire. The transport security mechanisms no longer apply once the data has reached the recipient, so if the data is logged on the recipient's machine, its confidentiality may be at risk. This is not the case with Web service security, where the security mechanisms are applied to the data itself.

For detailed information on implementing SSL and client certificates see Transport Security. For detailed information on implementing username/password authentication see Username/Password Authentication.

Web service security provides message-level security for web services through an implementation of the Oasis Web Service Security standard. Web service security, often referred to as "WS-Security" or simply "WSSE", lets you secure the SOAP messages that pass between web services with security tokens (username and password), digital signatures, and encryption.

An advantage of WS-Security is that the security mechanisms are applied to the SOAP messages that pass between web services. So WS-Security security mechanisms apply both while the SOAP message is in transit and once the message has arrived at the recipient's machine.The disadvantages of WS-Security are that it is not a widely used form of security and it is relatively more difficult to implement than the analogous transport security technologies. For example, users must be familiar with some of the inner workings of the Public Key Infrastructure (PKI) to effectively use WS-Security's encryption and digital signature technologies.

For detailed information on implementing see Web Service Security.

Role-based security lets you secure a web resource by restricting access to only those users who have been granted a particular security role. For detailed information on see Role-Based Security.

Transport Security

Transport security refers to a group of security technologies that ensure the authenticity of both clients and servers and the integrity and confidentiality of data passed between web servers and their clients.

In most cases, transport security alone is sufficient to secure a web resource such as a web application or web service; but there is another security option available specifically for web services. For detailed information see Web Service Security.

Transport Security Strategies

Transport security offers three basic strategies for achieving the three main security goals: authentication of participants, confidential communication and data integrity. See WebLogic Workshop Security Overview for a description of these security goals.

One-way SSL

One-way SSL offers two primary benefits. First it authenticates the identity of the web server. Second, it ensures confidential communication by encrypting the messages between the client and the server. The "one-way" in one-way SSL refers to the fact that only the identity of the server is authenticated, not the client. You should use one-way SSL when you want to ensure private communication, but where the identity of the client is not a critical factor.

One-way SSL with Basic Authentication

Basic authentication ensures the identity of clients by requiring a username and password. Basic authentication should always be used together with one-way SSL, otherwise the username and

password could be intercepted by a malicious third party. You should use one-way SSL when you want to ensure the identities of both the client and server. For details on implementing a basic authentication process, see Basic Authentication.

Two-way SSL

Two-way SSL combines server authentication, encryption of data, and client authentication through client digital certificates.

Web Service Security (WS-Security)

WebLogic Workshop provides message-level security for web services through an implementation of the WS-Security Oasis web service security standard. WS-Security lets you secure the SOAP messages passed between web services using (1) security tokens, (2) digital signatures, and (3) encryption.

Although WebLogic Workshop supports both transport and message-level security, it is generally not necessary to use both sorts of security to secure a web service. In most cases, developers should choose one or the other type of security to secure their web services.

Security Tokens

Security tokens are credentials used for authentication, authorization, or both. The WebLogic Workshop implementation supports two types of tokens. (1) Username and password tokens, and (2) X509 Binary Security Tokens.

When a X509 Binary Security Token accompanies an inbound SOAP message, the token is passed to the WebLogic Server security framework for authentication.

To include a Binary Security Token in an outbound SOAP message, you specify that you want to sign the outbound message. Signing the SOAP message will automatically include a X.509 BinarySecurityToken in the message. Note that sending a X509/Binary Security Token without signing the outbound SOAP message is not supported.

Digital Signatures

Digital signatures are used for two purposes: (1) to authenticate the identity of the sender and (2) to ensure the integrity of SOAP messages. If any part of an incoming SOAP message has been changed in transport, the signature validation performed by the recipient will fail. In WebLogic Workshop, if you require XML signatures for incoming SOAP messages, the SOAP body must be digitally signed to be processed by the web service.

By default, digital signatures are applied only to the body of outgoing SOAP messages. You must specifically provide for the signing of elements in the header. For details see in the WS-Security reference documentation.

Encryption

Encryption is used to encrypt either the body of the SOAP message, the header, or both. If your web service requires encryption for incoming messages, then, at a minimum, the body of incoming SOAP messages must be encrypted.

For outgoing SOAP messages, encryption is applied only to the SOAP body by default. You must specifically provide for the encryption of elements in the header. For details see in the WS-Security reference documentation.

Note that keys used in WebLogic Workshop's implementation of WS-Security must be RSA keys.

WSSE Policy Files

Web service security is controlled through WSSE policy files. WSSE policy files are XML files with a .WSSE file extension.

To secure a web service with web service security, you create a WSSE policy file and associate that file with your web service. All outbound and inbound SOAP messages are processed according to the policy called for in the WSSE file. Inbound messages are first checked for the necessary security measures called for in the policy file. If the inbound message is found to be appropriately secured, then the SOAP message, cleaned of its security enhancements, is passed to the web service for normal processing. Outbound messages go through the reverse process: they are enhanced with the security measures called for in the policy file before they sent out over the wire.

To access a web service secured with WS-Security, you create a policy file and associate that file with the web service control. The policy file you associate with a web service's control should match the policy file of the target web service. If the target web service requires encrypted incoming messages, then a control file targeting that web service should encrypt messages before they are sent to the web service.

For detailed information see Using WSSE Policy Files.

An Overview of Role-Based Security

The topics in this section explain how role-based security can be used to restrict access to resources (web services, page flows, Java controls, EJBs) to only those users who have been granted a particular security role. It also explains the relationship between EJB-scoped, application-scoped, web-application scoped, and global security roles.

To restrict access you set up two kinds of tests that candidate users must pass to access some resources: an authentication process, which determines the user's identity and group membership, and an authorization process, which decides whether a user has the role membership necessary to access a particular resource. Once a user has access to a method and the method executes, it can run under the security role of the user or under a different security role.

The Authentication Process

A candidate user is first tested against the authentication process. The authentication process is generally a login process, where the candidate user is asked to provide a username and password. If the candidate succeeds in passing this challenge, the user is granted a set of identities: one identity is his username identity, the other identities are the set of groups that user has membership in. The user's username identity and group identities are called the user's principals: think of these principals as a set of credentials that the user presents when he/she wants to access some resource protected by an authorization process. For more information, see Authentication.

The Authorization Process

In the authorization process, users are tested to see if they have been granted the required role to access the protected resource. If they have been granted the required role, they can access the resource; if they haven't, they are denied access. A user has been granted a particular role if one of his/her principals has been granted a particular role. Principals are granted roles by a set of role-principal mappings.

Note. A user can be a person or another software component. For instance, a web service can invoke an EJB's method with security restrictions; if the web service does not pass the authorization process, it is prevented from invoking the EJB method.

Global Roles

Global roles are available to all resources within a server's security realm, that is, a server's domain. These roles can be used by any application and any resource using this domain. WebLogic Server predefines a set of global roles but you can define additional global roles as needed. For more information, see the WebLogic Server help topic Securing WebLogic Resources.

Scoped Roles

Scoped roles apply to a particular resource. WebLogic Workshop applications can have three different scopings:

1. Application scoped (defined in the application's application.xml / weblogic-application.xml files) 2. Web application scoped (defined in a project's web.xml / weblogic.xml files) 3. EJB scoped (defined in an EJB's ejb-jar.xml / weblogic-ejb-jar.xml files)

Application scoped roles can be used in an authorization process to protect any of the resources within the application, whereas web application scoped roles apply only to the resources within an individual web project and EJB scoped roles apply only to the resources within an individual EJB. For instance, if you want a security role to be defined just for a particular EJB, you make it EJB-scoped.

Note that EJB scoped roles do not exclusively protect WebLogic Workshop's EJB projects: they also can be used to protect Web Services, Java control extensions (JCX files), and JPD files. This is because all these files are compiled into EJBs at compile time.

The following diagram shows the three kinds of scoped roles, and corresponding deployment descriptors, that you can define with WebLogic Workshop.

Note. You can also define scoped security roles for other resources such as JDBC resources. For more information, see the WebLogic Server help topic Securing WebLogic Resources.

Role-Principal Mapping

Role-principal mappings define how principals map to security roles. A particular user can be mapped to one or more security roles or a group can be mapped to one or more security roles. Role-principal mappings for a scoped role are defined in the appropriate deployment descriptor configuration file (see the fragments in the above picture; this is discussed in more detail in Implementing Role-Based Security).

For scoped roles, you can alternatively use the element to indicate that the role and role-principal mapping are defined elsewhere in the security realm. Specifically, when you use this element for EJB-scoped or web application scoped roles, WebLogic Server first examines the application-scoped roles for a role with the same name and with a role-principal mapping definition. If no appropriate application-scoped roles are found, global roles are examined. For application-scoped roles with the element, global roles are examined for role-principal mappings.

Note. When you map a scoped role to a principal, the principal is assumed to exist in the security realm. Role-principal mapping does not have the side effect of defining the principal if it doesn't exist. For more inforrmation, see Creating Principals and Role-Principal Mappings.

Running Under Another Security Role

An EJB, Java control, or web service method can run under the security role of the invoking user, or it can run under a different security role and principal. This might for instance be necessary when the EJB or web service in turn use resources that have strict security requirements.

Authentication

Authentication establishes the identity of a user by challenging the user to provide a valid username/password pair: something only the intended user knows.

Authentication can be used to protect any web-accessible resource, including web applications, web services, page flow applications, and individual JSP pages.

If the protected web resource is intended for human clients, the application can be configured to redirect users to a login page, where they must enter a valid username and password before they can access the resource. If the web resource is intended for machine clients, the machine client can provided the required username and password through methods on the resource's control file. For detailed information on authenticating machine clients see Using Controls to Access Transport Secured Resources.

The username/password pair can be checked against a variety of authentication provider services. A default authentication provider is provided by WebLogic Server, but other providers can be supplied as needed. For details on changing the default authentication provider or adding addition providers, see Configuring Security Providers in the WebLogic Server 8.1 documentation.

If you want to restrict access to sensitive information, username/password authentication should always be used in conjunction with SSL. Without SSL the username and password to are transported over the HTTP protocol, which uses only 64-bit encryption to hide the username and password, making it relatively easy for a malicious party to intercept and decode the message. For this reason you should always use basic authentication in conjunction with SSL, which uses 128-bit encryption.

However, if the primary purpose of username/password authentication is tracking user behavior in an application, and there is no especially sensitive information at stake, you do not need to use SSL.

Below are three basic strategies for setting up a username/password challenge in a WebLogic Workshop application:

Basic Authentication: uses a standard login screen provided by the web browser. Form Authentication: uses a custom login screen provided by the developer. Page flow authentication: uses a page flow to authenticate a user.

Basic Authentication

Basic authentication has the advantage of being easy to implement, but, since the login page is provided by the browser software, the developer does not have control over the look and feel of the login page. For detailed information see Basic Authentication. (Also see Developing BASIC Authentication Web Applications in the WebLogic Server 8.1 documentation.)

Form Authentication

Form authentication is easy to implement and gives the developer control over the look and feel of the login screen, but it should not be used in all situations. In particular it should not be used to secure (1) web services which have machine clients and (2) individual pages and methods within a page flow.

Web services with machine clients will encounter a problem interpreting the HTTP login page; instead use basic authentication for resources with machine clients.

Form authentication should not be used to secure individual pages and methods within a page flow. This is because form based authentication relies on redirecting the user from and back to the protected resource, but page flows do not support redirection from and back to the same location within a page flow. For this reason, you should only use form authentication to establish the identity of a user before he enters a page flow, not once he is within the page flow. If you want to allow a user to navigate within a page flow unauthenticated, but require authentication for other pages within the page flow use Page Flow Authentication.

For details on developing Form Authentication see Form Authentication. (Also see Developing FORM Authentication Web Applications in the WebLogic Server 8.1 documentation.)

Page Flow Authentication

Page Flow authentication uses a page flow to authenticate a user. The page flow can be a nested page flow, so it is appropriate to use this authentication technique when a user is already navigating within another page flow. For detailed information see Page Flow Authentication.

Portal Security Scenario

The following scenario describes the portal implementation needs of a fictitious company called Avitek, many of which involve security considerations. The topic that follows, Implementing the Portal Security Scenario, describes the security touch points in the scenario and provides links to implementation information.

Avitek needs two types of portal-based Web presence: an internal site for its employees and partners called "Inweb," and a public portal for its customers called "Outweb." It needs authentication for both sites. Inweb must live behind a firewall.

Outweb is set up on a server cluster for load balancing and failover.

For Inweb, Avitek needs to cater to three different types of users: managers, regular employees, and partners.

For the three types of users, Avitek wants to create only two portals: one for managers and employees and one for partners. Since there are five different partners, each partner must have a separate view of Inweb.

Some of the partners also perform contract work for Avitek, so they must also be able to access the employee portal desktop.

Avitek wants all Inweb users to authenticate before seeing any view of the portals.

For Outweb, Avitek provides information and services on a subscription basis, so it wants to provide a portal that lets all users see unsecured company information and log in to see secure information.

Avitek has a staff of two to administer all portals, and it wants to grant limited administrative access to certain partners to let them maintain their partner portal.

There are two JSP-based administration portlets that can never be seen by anyone other than Avitek's in-house administrators.

Avitek also wants to use its existing content management system for delivering content to its portals. The content management system vendor has created an interface to connect to BEA's Virtual Content Repository.

Avitek will use two user databases: The Intranet site will use an existing user database, and the public site will use the default WebLogic Server LDAP user database and is gradually adding users to it.

Deploying an Application to a Production Server

The following topic explains the basic concepts of deploying WebLogic Workshop applications to WebLogic Server running in production mode.

For step-by-step instructions on deploying a WebLogic Workshop application to a production server see How Do I: Deploy a WebLogic Workshop Application to a Production Server?.

Development Mode and Production Mode

Weblogic Server can be started in one of two modes: development or production mode. Development mode is the default. When you are developing, deploying and testing an application with WebLogic Workshop, the instance of Weblogic Server you are running is in development mode. In development mode, WebLogic Server behaves in ways that make it easier to iteratively develop and test an application: it automatically deploys the current application in an exploded format, server resources such as databases and JMS queues necessary for the application to run are automatically created, etc.

When the development cycle is complete, and the application is ready for use, you deploy it to an instance (or instances) of WebLogic Server running in production mode. In production mode applications are not automatically deployed. The server resources necessary for running an application are not automatically generated, you must generate them manually.

To set the server to start in production mode, you specify the Java property mode in the startup script as:

-Dweblogic.ProductionModeEnabled=true

For detailed information on starting WebLogic Server in production or development mode see startWebLogic Command.

EAR Files

WebLogic Workshop produces J2EE enterprise applications for deployment to a production server. You cannot deploy a web application project alone as a Web Application Archive (WAR) file; it must be deployed as a part of an entire application. There are two ways to deploy an application on the production server: in an exploded directory, or in an archive.

In an archived format, use EAR files if you are deploying an entire application; or use a JAR file if you are deploying a specific project within an application, (provided that specific project is a custom Java control or a Schema project).

You can generate an EAR file for a WebLogic Workshop application either (1) from the menu bar by selecting Build-->Build EAR or (2) by using the wlwBuild.cmd command line tool. The wlwBuild.cmd line tool is somewhat more flexible in that you can set flags to build a JAR file for a specific project, instead of building an EAR file for the entire application.

For information generating an ANT build.xml file that calls wlwBuild.cmd, see How Do I: Call wlwBuild.cmd from an ANT build.xml file?

EAR files can be deployed to WebLogic Server using either (1) the WebLogic Server console, or (2) the weblogic.Deployer utility.

To use the WebLogic Server console to deploy an EAR file, start the console, expand the Deployments node in the left-hand pane, right-click the Applications node, and select Deploy a new Application.

To use the weblogic.Deployer utility see the Deployment Tools Reference in the WebLogic Server 8.1 documentation.

When you compile an EAR file using Build EAR, a wlw-manifest.xml file is produced and placed in the application's META-INF directory. This wlw-manifiest.xml file lists the server resources that must be created on the production server for the application EAR to run successfully. See the next section for information relating to the wlw-manifest.xml file.

Note: Values specified in a project's WEB-INF/wlw-config.xml file, such as hostname, http-port, and https-port, will be hard-coded into the EAR file. The result will be an EAR file that can be run only on the machine named in the wlw-config.xml file. For this reason, it is recommended that you do not write to the wlw-config.xml file before producing an EAR file. If you need to override the hostname and ports dynamically determined by the server at runtime, use the wlw-runtime-config.xml file instead of wlw-config.xml.

Manual Creation of Server Resources

When deploying EAR files to a production server, a certain amount of manual resource creation is necessary. When an application is built in an EAR file, a wlw-manifest.xml file is produced and placed in the application's META-INF directory. This file lists the JMS queues and database tables that need to be manually created on the target WebLogic Server for the application to run properly.

Note: When you use iterative builds, the builds do not include a clean step. To ensure an accurate wlw-manifest.xml file, make sure your final build includes a clean step. Otherwise, the contents of the wlw-manifest.xml may not be correct.

Note: When you are developing and testing an application with WebLogic Workshop, the creation of the necessary JMS queues and datatables on WebLogic Server takes places automatically on demand.

Required database tables are indicated by a tag. These tables are used by web services to store conversational state. For each occurrence of the tag in the wlw-manifest.xml file, you must create a corresponding datatable on WebLogic Server. For detailed information about the schema required for these tables, see How Do I: Deploy a WebLogic Workshop Application to a Production Server?

Required JMS queues are indicated by pairs of and tags. For each occurrence of these tags in the wlw-manifest.xml file, you must create a corresponding JMS queue on WebLogic Server and you must associate the members of the pair by referencing the in the ErrorDestination attribute of the . For detailed information about how to create these queues, see How Do I: Deploy a WebLogic Workshop Application to a Production Server?

Optionally, you may want to enforce role restrictions on any controls that receive external callbacks. Controls that can receive external callbacks are indicated within a tag in the wlw-manifest.xml file. Since the compilation process turns control files into individual methods on an EJB, you enforce the role restrictions on these post-compilation EJB methods.

Overview: Clustering

A WebLogic Server cluster is a deployment in which multiple copies, or instances, of an application work together to provide increased performance, especially in high traffic contexts. In cases where an application receives a high volume of requests, the different instances of WebLogic Server in the cluster share the work of processing the requests. From the client’s point of view, there appears to be only one instance of WebLogic Server servicing the requests.

Clusters also provide failover support. Should one instance of the application fail for some reason--for example, because of a hardware outage--another copy of the application in the cluster can pick up and complete the tasks left incomplete by the failed server.

The server instances that make up the cluster can run on a single machine, or they can run on different machines. Each server instance in a cluster must run the same version of WebLogic Server.

To learn more about deploying applications to WebLogic Server clusters see WebLogic Server Clusters in the WebLogic Server 8.1 Documentation.

Clustering Workshop Applications

Clusters provide scalability and support failover for web resources. The basic clustering model consists of the following elements:

1. One administration server that manages state and configures the other servers in the cluster 2. One HTTP proxy server—either a hardware or a software proxy server—which receives

requests from clients and distributes jobs to the other servers in the cluster 3. Any number of managed servers that actually do the work of servicing requests from clients

All configuration of the cluster takes place on the administration server: all other servers in the cluster use the copy of config.xml on the administration server. (There may be local copies of config.xml on the managed servers in the cluster, but, these copies of config.xml are ignored in favor of the copy on the administration server.)

The following three required WebLogic Workshop resources must also be deployed homogeneously across all servers in a cluster:

JDBCConnectionPool JDBCTxDatasource JMSQueueConnectionFactory.

A JMS Server is also a required Workshop resource, however, it can only be deployed to one server in the cluster.

Configuring Clusters in config.xml

Complete syntax for the config.xml file can be found at WebLogic Server Configuration Reference in the WebLogic Server 8.1 documentation.

The following sections highlight some of the most important elements within a cluster-defining config.xml file (located on the administration server), including the element, resource deployment, and database support.

The Element

The ClusterAddress attribute specifies a DNS name that maps to the list of IPs of the servers. ClusterAddress does not give the DNS name of the multicast address, which does not require a DNS name. The cluster as a whole can be used as a deployment target. To deploy a J2EE resource to the entire cluster, use the value of the Name attribute as the target of the deployment. To learn more, see the -targets parameter of the deployment tool, Deployment Tools Reference, in the WebLogic Server 8.1 documentation.

Resource Deployment

Resources in the cluster—such as database connection pools, data sources, and JMS servers—are defined in the administration server's config.xml file. Resources are not by default universally available across the cluster. The servers they are deployed to are specified by their Targets attributes.

The connection pool, conversational datasource, and queue connection factory that Workshop relies on is defined on each managed server in the cluster. For example, the Targets attribute on the JDBConnectionPool and JDBCDataSource elements specifies each managed server, and each managed server has its own pool of connections.

However, the JMSServers can only be targeted at one server in the cluster. Currently Workshop only uses one JMSServer that is targeted, by convention, at the first managed server in the cluster.

Proxy Server Setup

Clusters can use a software proxy server to distribute HTTP requests across the cluster. The proxy server is also called the sprayer or load balancer. This software proxy is implemented as a web application deployed to the proxy server. You configure the proxy by editing the web.xml descriptor in the proxy application’s WAR file. There are entries in the descriptor for specifying what IP addresses and ports the proxy should distribute requests to. For more information about configuring the proxy server see Configure Proxy Plug-Ins in the WebLogic Server 8.1 documentation.

When using a proxy, it is necessary to set the hostname, HTTP, and HTTPS ports on the target cluster, otherwise the target cluster will not know how to interpret the requested URLs coming from the proxy. You set the hostname and ports by (1) setting the FrontEnd information through the WebLogic Server console and (2) in the target cluster's the wlw-runtime-config.xml file.

Editing the application's wlw-config.xml file is not recommended, because these values are fixed at compile-time. It is generally best to configure the hostname and ports through the wlw-runtime-config.xml file, which overrides the values in the wlw-config.xml.

To set the FrontEnd host and port information using the WebLogic Server console, open the console, and navigate to

[your_domain]-->Servers-->[your_server]-->Protocols tab-->HTTP tab-->Advanced Options

Then edit the Frontend Host, Frontend HTTP port, and Frontend HTTPS port fields. Note that the Frontend host must be set on each managed server in the cluster, but should not be set on the administration server. All servers in the cluster must be restarted for this change to take effect. Configuring Web Server Functionality for WebLogic Server

To set the host and port information in the wlw-runtime-config.xml file see wlw-runtime-config.xml in the WebLogic Workshop reference documentation.