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:
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.
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.
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 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.
The following diagram shows the different objects and the method you use to call an invoked listener.
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.
This table lists the SilverStream objects on which the invokeBusinessObject() method is available from the SilverStream Designers.
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().
You return data to the calling program the same way, regardless of how the object is invoked.
invokeBusinessObject() method. You use the getParameter() method available on the invoked event to obtain it, as shown here:
Hashtable param = (Hashtable)evt.getParameter();
setResult() method on the event object, for example:
evt.setResult(myObject);
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.
evt.setResultMIMEType("text/hmtl");
evt.setResult(myHTMLtext, "text/hmtl");
or
evt.setResult("Some text string", "text/plain");
For documented code examples of running applications that use invoked business objects, go to Application Techniques>Triggered Business Object Techniques:
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.
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:
init() method to initialize SilverStream classes, and use the connect() method to instantiate an AgrServerSession on the SilverStream Server. AgrServerSession.invokeBusinessObject() to invoke the listener. One version of the method allows you to pass an argument to the invoked object.
For more information about connecting external Java clients with the SilverStream Server, see
Writing External Java Clients
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.