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:
Ways to Think About Custom Controls
Working with Java Control Sources
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:
Built-in and custom Java controls. WebLogic Workshop provides several built-in controls, and you can build your own.
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:
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.
Local controls and control projects. You can use controls locally as source, or group them into control projects.
Regular and customizable controls. Some controls provide a static interface, some are customizable.
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.