Passing Parameters to an Echo application.
By Brad Baker
Tuesday, July 27, 2004
One of the most powerful features of the world wide web is hyperlinking. That is linking one web page with another via URLs.
However its not without its difficulties. In a complex web application, you have to remember what state you are in and make sure the URL parameters are just right and the application state is passed on and... well, you know the score.
In an attempt to handle this automatically for you, Echo has broken away from using URL parameters as a way of tracking application state. You are not required to ensure any particular URL parameter is saved, kept or present. And for the most part thats a good thing.
However it means that standard URL linking techiniques do not work out of the box with an Echo web application.
The good news is that, of course, there are ways to acheive this.
Passing Information Into Echo
Lets us first look at passing information into an Echo web application. There are several scenarios involved here.
- The Echo application is not started.
- The Echo application is already started.
- The parameters are to be passed via an HTTP GET.
- The parameters are to be passed via an HTTP POST.
Scenario 1 is handled by the new Echo 1.1 nextapp.echoservlet.InitialParameters interface. This interface represents the URL parameters that where passed to the Echo web application when it was first started. In essence this interface wraps a Map of parameter names and thier values.
An instance of InitialParameters is placed inside the EchoInstance attributes with the name InitialParameters.ATTRIBUTE_NAME. You can retrieve this using the following code
InitialParameters ip = (InitialParameters) youEchoInstance.getAttribute(InitialParameters.ATTRIBUTE_NAME);
Once you have the inital parameters you can decide what you want to do with them.
Scenario 2 is handled by the echopoint.ExternalEventMonitor component. This is non visual component that can raise events when specific URL parameters are processed by the Echo framework. You need to embed an instance of ExternalEventMonitor into you application and wire it to an object that implements echopoint.event.ExternalEventListener. The listener code will look a little like this :
public void externalEvent(ExternalEvent externalEvent) {
String[] paramNames = externalEvent.getParameterNames();
for (int i = 0; i < paramNames.length; i++) {
String[] paramValues = externalEvent.getParameterValues(paramNames[i]);
for (int j = 0; j < paramValues.length; j++) {
System.out.println(paramNames[i] + "=" + paramValues[j]);
}
}
}
An echopoint.event.ExternalEvent will be raised every time an Echo servlet URL is invoked with one caveat. It must have a parameter with the name and value
E_id=ExternalEvent.
This special parameter is required to tell the Echo framework that the URL needs special treatment.
(In fact this is how you invoke a special Echo object called a nextapp.echoservlet.Service. But I dont want to go into that right now, but just know this is how the ExternalEventMonitor does its stuff.)
Your URL must therefore look something like this :
/servletcontext/servlet?E_id=ExternalEvent&p1=v1&p2=v2
The ExternalEvent object would contain 2 parameter names (p1 and p2) with a 1 value each (v1 and v2).
Scenario 3 and Scenario 4 are automatically handled for you. It doesnt matter whether the invoking web application uses HTTP GET or HTTP POST when passing the parameters. The standard Java Servlet technology makes this available as named string parameters.
Passing Information Out Of Echo
To perform the opposite function, that is to pass information from an Echo application to another web page, other mechanisms are used. In essence you need to suspend or exit the Echo instance and redirect to the other web page. You do this via the nextapp.echoservlet.ServerContext interface.
nextapp.echoservlet.ServerContext sc = (nextapp.echoservlet.ServerContext) getEchoInstance().getAttribute(nextapp.echoservlet.ServerContext.ATTRIBUTE_NAME);
Once you have an instance of this interface, you can call suspend() or exit(). An optional parameter is the URL to redirect to after the EchoInstance is suspended or terminated. For example :
sc.suspend(http://echopoint.sourceforge.net?p1=v1&p2=v2);
This would suspend the current EchoInstance and would pass the p1 and p2 parameters to the other web site, using a standard HTTP GET.
There is a helper component called echopoint.ExitButton that will suspend or exit the application when pressed. This hides obtaining the ServerContext from your code.
If the target web application requires a HTTP POST, then you can use the echopoint.SubmitButton component. You simply add parameter names and values to this Button component, plus a target URL. For example :
SubmitButton submitB = new SubmitButton(null,"Submit Me");
submitB.setURI("http://echopoint.sourceforge.net");
submitB.addParameter("p1","v1");
submitB.addParameter("p1","v2");
When this button is pressed, the added parameter names and values will be posted to the target URL.
![[Image]](../Images/echopoint_threesisters.jpg)