Skip Headers
Oracle® Application Development Framework Developer's Guide For Forms/4GL Developers
10g Release 3 (10.1.3.0)
B25947-01
  Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
 
Next
Next
 

8.4 Publishing Custom Service Methods to Clients

When you add a public custom method to your application module class, if you want clients to be able to invoke it, you need to include the method on the application module's client interface.

8.4.1 How to Publish Custom Service Methods to Clients

To include a public method from your application module's custom Java class on the client interface, use the Client Interface page of the Application Module Editor. As shown in Figure 8-5, select one or more desired methods from the Available list and press > to shuttle them into the Selected list. Then click OK to dismiss the editor.

Figure 8-5 Adding a Public Method to an Application Module's Client Interface

Image of Client Interface dialog

8.4.2 What Happens When You Publish Custom Service Methods to Clients

When you publish custom service methods on the client interface, as illustrated in Figure 8-6, JDeveloper creates a Java interface with the same name as the application module in the common subpackage of the package in which your application module resides. For an application module named SRService in the devguide.model package, this interface will be named SRService and reside in the devguide.model.common package. The interface extends the base ApplicationModule interface in the oracle.jbo package, reflecting that a client can access all of the base functionality that your application module inherits from the ApplicationModuleImpl class.

Figure 8-6 Custom Service Interface Extends the Base ApplicationModule Interface

Image of interface extending application module interface

As shown in Example 8-7, the SRService interface includes the method signatures of all of the methods you've selected to be on the client interface of your application module.

Example 8-7 Custom Service Interface Based on Methods Selected in the Client Interface Panel

package devguide.model.common;
import oracle.jbo.ApplicationModule;
// ---------------------------------------------------------------------
// ---    File generated by Oracle ADF Business Components Design Time.
// ---------------------------------------------------------------------
public interface SRService extends ApplicationModule {
  long createProduct(String name, String description);
  String findServiceRequestStatus(long requestId);
  String findServiceRequestTechnician(long requestId);
  void updateRequestStatus(long requestId, String newStatus);
}

Each time you add or remove methods from the Selected list in the Client Interface page, the corresponding service interface file is updated automatically. JDeveloper also generates a companion client proxy class that is used when you deploy your application module for access by a remote client. For the SRService application module in this example, the client proxy file is called SRServiceClient and it is created in the devguide.model.client subpackage.


Note:

After adding new custom methods to the client interface, if your new custom methods do not appear to be available using JDeveloper's Code Insight context-sensitive statement completion when trying to use the custom interface from client code, try recompiling the generated client interface. To do this, select the application module in the Application Navigator, select the source file for the interface of the same name in the Structure window, and choose Rebuild from the context menu. Consider this tip for new custom methods added to view objects and view rows as well.

8.4.3 How to Generate Client Interfaces for View Objects and View Rows

In addition to generating a client interface for your application module, it's also possible to generate strongly typed client interfaces for working with the other key client objects that you can customize. In a manner identical to how you have learned to do for application modules, you can open the Client Interface and Client Row Interface pages of the View Object Editor to add custom methods to the view object client interface and the view row client interface, respectively.

If for the ServiceRequests view object in the devguide.model.queries package you were to enable the generation of a custom view object Java class and add one or more custom methods to the view object client interface, JDeveloper would generate the ServiceRequestsImpl class and ServiceRequests interface, as shown in Figure 8-7. As with the application module custom interface, notice that it gets generated in the common subpackage.

Figure 8-7 Custom View Object Interface Extends the Base ViewObject Interface

Image of view object interface extending another interface

Likewise, if for the same view object you were to enable the generation of a custom view row Java class and add one or more custom methods to the view row client interface, JDeveloper would generate the ServiceRequestsRowImpl class and ServiceRequestsRow interface, as shown in Figure 8-8.

Figure 8-8 Custom View Row Interface Extends the Base Row Interface

image view row interface extending the Base Row Interface

8.4.4 What You May Need to Know About Method Signatures on the Client Interface

You can include any custom method in the client interface that obeys these rules:

  • If the method has a non-void return type, the type must be serializable.

  • If the method accepts any parameters, all their types must be serializable.

  • If the method signature includes a throws clause, the exception must be an instance of JboException in the oracle.jbo package.

In other words, all the types in its method signature must implement the java.io.Serializable interface, and any checked exceptions must be JboException or its subclass. Your method can throw any unchecked exception — java.lang.RuntimeException or a subclass of it — without disqualifing the method from appearing on the application module's client interface.


Note:

If the method you've added to the application module class doesn't appear in the Available list, first check to see that it doesn't violate any of the rules above. If it seems like it should be a legal method to appear in the list, try recompiling the application module class before visiting the Application Module Editor again.

8.4.5 What You May Need to Know About Passing Information from the Data Model

The private implementation of an application module custom method can easily refer to any view object instance in the data model using the generated accessor methods. By calling the getCurrentRow() method on any view object, it can access the same current row for any view object that the client user interface sees as the current row. Due to this benefit, in some cases while writing application module business service methods there is no need to pass in parameters from the client if they would only be passing in values from the current rows of other view object instances in the same application module's data model.

For example, the createServiceRequest() method in the SRDemo application's SRService application module accepts no parameters. Internally it calls getGlobals().getCurrentRow() to access the current row of the Globals view object instance. Then it uses the strongly typed accessor methods on the row to access the values of the ProblemDescription and ProductId attributes to set them as the values of corresponding attributes in a newly-created ServiceRequest entity object row.

Example 8-8 Using View Object Accessor Methods to Access a Current Row

// In SRServiceImpl.java, createServiceRequest() method
GlobalsRowImpl globalsRow = (GlobalsRowImpl)getGlobals().getCurrentRow();
newReq.setProblemDescription(globalsRow.getProblemDescription());
newReq.setProdId(globalsRow.getProductId());