Creating a New EJB Control

Enterprise JavaBean (EJB) controls make it easy for you to use an existing, deployed session or entity EJB from within an application. To create an EJB control, you must first make sure that the EJB's (local or remote) home and business interfaces are available to your application.

Making EJB Interfaces Available to Your Application

Before you can create an EJB Control, the EJB's local or remote interfaces must be known in your application. If the EJB is not part of the application, you make it available by adding the EJB's JAR file to your WebLogic Workshop application. While the complete EJB JAR file allows WebLogic Workshop to access the EJB's interfaces, the only classes actually required are the EJB's home and remote interface classes and any other classes used externally by the EJB (for example, as method parameters or method return types). The EJB compiler ejbc is capable of producing a client JAR that will serve this purpose. To learn more about EJB client JAR files, see @ejbgen:jar-settings Annotation. To learn more about adding EJB Jar files, see How Do I: Add an Existing Enterprise JavaBean to an Application?

Creating a New EJB Control

You can create a new EJB control and insert it into your page flow or web service application at the same time, or you can create a new EJB control without insertion, for instance when you are developing in a Control project.

You can add a Web Service control in any of the following types of files:

  • Java Control (JCS file)
  • Java Page Flow (JPF file)
  • Java Server Page (JSP file)
  • Java Web Service file (JWS file)
  • Process file (JPD file)

To insert a new EJB control

  1. Make sure you have opened the target web service or page flow controller file. For web services, if you are not in Design View, click the Design View tab. For page flows, click the Action View tab.
  2. Display the Data Palette (View->Windows->Data Palette).
  3. On the Data Palette, click the Add drop-down, and choose EJB Control. The Insert Control - Insert EJB Control dialog opens.
  4. In the Variable name for this control field, type the name for your EJB control.
  5. Select the Create a new EJB control to use radio button.
  6. In the New JCX name field, type the name of the new file.
  7. Decide whether you want to make this a control factory and select or clear the Make this a control factory that can create multiple instances at runtime check box. For more information about control factories, see Control Factories: Managing Collections of Controls.
  8. In the Step 3 pane, click the Browse application EJBs or Browse server EJBs button. The Available EJBs dialog appears.

    The Browse application EJBs button will return a list of all the EJBs known within the current application. These are EJBs developed in the application as well as EJBs defined in EJB JARs added as modules to the application. If only the EJB's local interface is defined, the EJB will appear in the list with a local ejb-link reference, as is shown in the below screenshot for the CreditCard bean. If an EJB's local interface and local JNDI name are defined, the EJB will also appear with a local jndi reference, as is shown below for the Address bean. The same analogy applies to remote interfaces. The Customer bean below, whose remote and local interfaces and JNDI names are defined, appears four times.

    An ejb-link locates a bean relative to its EJB JAR within the application. In source code, this might look like @jc:ejb ejb-link="MyEJBProject.jar#Music". For more information, see the @jc:ejb reference documentation.

    The Browse server EJBs button will return a list of all the EJBs known on the server used by the current application. Only included in this list are EJBs whose remote (home and business) interfaces are defined.

  9. Select the appropriate EJB from the list and click Select. The name appears in the jndi-name field, and the interfaces used by this EJB appear in the home interface and bean interface fields.
  10. Click Create.

To create a new EJB control

  1. Locate or create the folder where you want to create the EJB control. This can be a folder in a Control project, Web project, or Web Service project.
  2. Right-click the folder and choose New-->Java Control. The New Java Control dialog opens.
  3. In the top pane, select EJB Control. In the File name field, enter the name of the new EJB control. Click Next.
  4. Click the Browse application EJBs or Browse server EJBs button. The Select EJB dialog appears. Go to step 7 above and follow the instructions.

When you open the EJB control in Design View, you might notice that no methods are shown. For more information, see the next section.

Modifying EJB Controls

If you open an EJB control in Source View, you will notice that the control simply extends the EJB's interfaces. Unlike some other controls, the EJB control's class definition does not contain method declarations that invoke the EJB's methods. In other words, the EJB control only serves to reference the EJB and to expose its methods, and cannot be used to limit access to, or modify, these methods. To modify access to the EJB's methods, you must redefine the EJB's interfaces.

To see the EJB methods exposed by the EJB control, insert an EJB control in a web service or page flow, or, for control projects, build the EJB control's control project.

When you modify the EJB's methods or add additional methods to the interfaces that the EJB control references, you do not need to modify the EJB control (but you must rebuild the EJB). When you modify the name of the used interfaces, the JNDI name (if the EJB control uses the jndi name), or the bean name or EJB JAR name (if the EJB control uses a ejb-link), you must modify the EJB control to reflect these changes.

Accessing EJBs on a Different Server

You can access EJBs on a different server with an EJB control, provided the server hosting the EJB control and the server to which the target EJB is deployed are in the same domain. You access EJBs on a different server by using special JNDI syntax in the jc:ejb tag's home-jndi-name attribute. For example:

@jc:ejb home-jndi-name="jndi://username:password@host:7001/my.resource.jndi.object"

You can also use environment properties to specify configuration information, such as:

@jc:ejb home-jndi-name="jndi://host:7001/MyEJBHome?SECURITY_PRINCIPAL=me&SECURITY_CREDENTIALS=passwd"

For more information on environment properties, see the JNDI Tutorial.

You can also override the value of the @jc:ejb home-jndi-name attribute using the EJB control method setJndiName(). For more information see Setting the Target EJB Information at Runtime below and setJndiName().

To make an EJB control for an EJB on a different server, use the New Control wizard as described above to create an EJB control for an EJB on the local server (or duplicate an existing EJB control), and then go to Source View to adjust the jc:ejb tag and the names of the interfaces.

Note: Accessing a remote EJB in a different domain via the EJB control requires advanced transaction configuration. Please consult the "Configuring Domains for Inter-Domain Transactions" section of the Administration Console Online Help topic in the WebLogic Server documentation on e-docs.bea.com.

Setting the Target EJB Information at Runtime

You can set the target EJB information at runtime using the EJB control method setJndiName(). The method can set the host, port, and JNDI name of the target EJB. The values set by setJndiName() override those set by @jc:ejb home-jndi-name. If no EJB is found at the location set by setJndiName(), then the value set by @jc:ejb home-jndi-name is used as a fallback.

The setJndiName() method takes the same syntax as the @jc:ejb home-jndi-name annotation. To set a new JNDI name, without setting a new server or port, use the following syntax.

    myEJBControl.setJndiName("my.resource.jndi.object");

To set a new JNDI name, server and port, use the following syntax.

    myEJBControl.setJndiName( "jndi://username:password@host:7001/my.resource.jndi.object" );

Related Topics

Using WebLogic Built-In Controls

Using an EJB Control

How Do I: Create and Use a Java Control Within a Control Project?

How Do I: Add an Existing Enterprise JavaBean to an Application?

How Do I: Test an Enterprise JavaBean?

Tutorial: Enterprise JavaBeans