Programmer's Guide

Chapter 29   Using Invoked Business Objects

SilverStream's invoked objects are triggered business objects that you can call from a SilverStream form, page, or other business object, or you can call them from a client developed outside of SilverStream. This chapter has the following topics:

About invoked business objects   Top of page

An invoked triggered business object (or invoked listener) is a type of SilverStream business object that implements the AgiInvokedListener interface. Objects that implement this interface are registered with the application server to "listen" for invoked events.

In SilverStream you can call an invoked listener from a form, page or another business object by calling the invokeBusinessObject() method. The calling form, page, or business object can pass an Object to the invoked listener and from it obtain a result of type Serializable.

Creating an invoked listener   Top of page

When you create a triggered business object using the SilverStream Business Object Designer, SilverStream adds the implements AgiInvokedListener clause to the object's class definition and registers the object as an invoked listener. To be a registered listener means that the object lets the server know that it wants to be notified when the server receives a specific type of event.

Importing an invoked object created externally

You can create a Java class in an external editor that implements AgiInvokedListener, then import the source or class file using the SilverCmd ImportSource and ImportClass commands.

    For information see the SilverCmd Reference in the online Tools Guide.

Invoked listeners and synchronization    Top of page

Invoked listeners are called from SilverStream objects synchronously. This means that the caller is blocked for input while waiting for the Invoked object to complete. SilverStream returns control to the caller when the invoked listener's invoked event completes. If the object is unable to execute or encounters an error condition, SilverStream throws an exception.

Because the object is called synchronously, you must carefully consider how to program it. If the invoked listener must do a lot of processing, which could be time-consuming, you might want to avoid invoking it from a form or page where the user will have to wait for the process to complete.

As an alternative, you can spawn a thread and invoke the object in the new thread, thus causing only the new thread to block.

Using invoked listeners in SilverStream   Top of page

The following diagram shows the different objects and the method you use to call an invoked listener.

Calling the invoked listener    Top of page

To call an invoked listener, you use the invokeBusinessObject() method. The invokeBusinessObject() method is available to forms, pages, and other business objects through different classes or interfaces.

The invokeBusinessObject() method has two variants. Both versions return an Object to the caller. You set the result in the listener code by calling setResult() on the AgoInvokedEvent object passed to the listener.

With this variant, you simply pass the business object name:

  Serializable invokeBusinessObject(String agentSpec) throws Exception 

where agentSpec is the fully qualified name (including package) of a business object to invoke. To call a business object in a different database on the same server, prepend the name of the database and a colon (:) to the name. When you use this variant, the evt.getParameter() method returns null.

This variant allows you to pass a parameter to the business object:

  Serializable invokeBusinessObject(String agentSpec,Serializable param) throws Exception 

where param is a parameter to pass to the business object.

NOTE   You cannot specify the IP address of the server or the full server name.

About the calling objects   Top of page

This table lists the SilverStream objects on which the invokeBusinessObject() method is available from the SilverStream Designers.







Business object






Calling from pages

For pages, the invokeBusinessObject() method also throws the AgoUnsupportableOperationException. The method must be called while the page is processing an HTTP request, otherwise the system throws this exception.

Calling from business objects

invokeBusinessObject() is not available directly to the calling business object. To invoke a listener from a business object, you must obtain a reference to the database in which the listener resides by calling the evt.getDatabase() method. Once you have obtained the AgiDatabase, you can call AgiDatabase.invokeBusinessObject().

Returning data to the caller   Top of page

You return data to the calling program the same way, regardless of how the object is invoked.

  1. The invoker of the business object can pass a parameter to the event when it calls the invokeBusinessObject() method. You use the getParameter() method available on the invoked event to obtain it, as shown here:

      Hashtable param = (Hashtable)evt.getParameter(); 
  2. The listener can perform whatever processing you want within the invoked event.

  3. Invoked business objects can return data to the caller. It can be any Object. You set this result by calling the setResult() method on the event object, for example:


Setting the returned data

Returned results can be Java objects (which must be Serializable) or if invoked from an HTML page, anything that a browser could handle (HTML, images, and so on). The type of the result is set by specifying a MIME-Type. By default, the MIME-Type of the returned result defaults to application/octet-stream. You should use this for Java objects. If you want to return HTML, plain text, or an image, then you must set the MIME-Type of the result appropriately (for example, text/hmtl, text/plain, image/jpg, etc).

There are two ways to set the MIME-Type of the result.

Examples of using invoked business objects   Top of page

For documented code examples of running applications that use invoked business objects, go to Application Techniques>Triggered Business Object Techniques:

Invoking listeners from non-SilverStream Java clients   Top of page

If you have a number of applications developed outside of SilverStream, you might want to access invocable objects on the SilverStream Server in order to share business logic. SilverStream provides support for invoking listeners from external Java clients and from external HTML forms.

Invoking listeners from external Java clients   Top of page

You can use the SilverStream API to establish a session on the SilverStream Server from a non-SilverStream Java client. This connection provides the same session management support you get when working with SilverStream forms. This means, for example, that you do not need to track sessions when invoking objects from the external source.

When connecting to the SilverStream Server from non-SilverStream client, you do the following:

    For more information about connecting external Java clients with the SilverStream Server, see Writing External Java Clients

Calling an invoked listener on a remote server   Top of page

You can also use the AgRuntime class to create an AgrServerSession on a remote server, then use the AgrServerSession.invokeBusinessObject() method to call the invoked listener on that server.

    For more information, see the API help page for AgRuntime.

Copyright © 2000, SilverStream Software, Inc. All rights reserved.