How to use the Web Services API

The Web Services API provides applications the ability to interact with ViewsFlash. They can be other Java web applications in the same Java Virtual Machine, or any application on any server using the HTTP query protocol. The API calls require composing a query string and invoking the ViewsFlash application using a RequestDispatcher or an HTTP query. All Web Services API requests must pass appropriate security checks. The sections below specify in detail how to construct and send these queries.

Using the RequestDispatcher include() method

The information in this section is appropriate not only for the Web Services API, but for any application that wants to include the ViewsFlash application. These include: wrapping the viewsflash servlet inside another servlet to provide custom security and embedding questionnaires in JSP pages.

This method is available when the ViewsFlash application is deployed in the same Java Virtual Machine as the Java program that is using the Web Services API. If this is a JSP page, and the page is not in the ViewsFlash context, it may be ncessary to enable cross-context access in the Application Server. In Tomcat, in particular, this is done with a Context element; see the ViewsFlash/META-INF/ViewsFlash.xml file.

As of release 5.6, access to the Web Services API from JSP pages must be enabled explicitly with the "apiattribute" servlet parameter:
apiattribute=com.cogix.vwf.api

The JSP page must set this request attribute to the current time in milliseconds to authenticate itself.

The following example uses the API to request a list of all questionnaires in a Place. It uses a query string cmd=getpollnames&status=open&spotname=NAME

String place = "Examples"; // the name of the Place
String apiparams = "cmd=getpollnames&status=open&spotname=" + place ; // cmd=getpollnames&spotname=Examples

String resultsattribute = "com.cogix.vwf.response"; // the name of a request attribute
String directtheresponse = "&outputtorequestattribute="+ resultsattribute; // instructs the API to deliver its response in a request attribute

// Get the Context in a JSP page:
ServletContext otc = pageContext.getServletContext(); // use this when the JSP page lives inside the ViewsFlash application
// ServletContext otc = application.getContext("/ViewsFlash"); // use a cross-context reference only when this JSP page lives in a context outside /ViewsFlash

// If not in a JSP page, but rather in a web application, use getContext() or getServletContext().getContext("/ViewsFlash") instead.

// Construct the query string
String query = apiparams + directtheresponse; // do not use a leading ?
request.setAttribute("com.cogix.vwf.onlyquery", query); // Place the query string in this attribute to ignore all request parameters available using request.getParameter()
request.setAttribute("com.cogix.vwf.api", new Long(System.currentTimeMillis())); // set this attribute to the current time to establish security credentials

// Find the request dispatcher
String servletpath = "/servlet/viewsflash"; // servlet that responds to Web Services API requests
RequestDispatcher rd = otc.getRequestDispatcher (servletpath);

// include
rd.include(request, response); // pass the request to the servlet

// work with the response
String respond = (String) request.getAttribute(resultsattribute); // retrieve the Web Services API response to the request
if ( respond != null ) // if response were null, there has been a malfunction. Most likely cause: /servlet/viewsflash not found in the Context, or authentication failure
out.print ( respond ); // this example would display a list of all the questionnaire ID's in the Place

Frequently asked questions

How do you pass parameters to the ViewsFlash servlets?
Many application servers allow adding "?name=value" parameters to the servlet path passed to the RequestDispatcher.
However, when processing the include(), ViewsFlash will process parameters from both this query string and request parameters that were available to the JSP page. This can lead to paramter conflict or duplication. Some application servers ignore this query string. To avoid this problems, it is better to place the query string in one of these HttpRequest attributes:

Use "com.cogix.vwf.onlyquery" to ignore the original request query and all request parameters and use the parameters in this query string
Use "com.cogix.vwf.onlyqueryandparams" to use the available request parameters as well as the parameters in this query string

How do you find the /servlet/viewsflash servlet?
Use getContext ("/ViewsFlash") and getDispatcher ("/servlet/viewsflash"), as shown in the example. It may be necessary to enable "cross-context" processing, as in Tomcat's ViewsFlash.xml ( or server.xml ).
If working inside a web application in Java code (instead of a JSP), then find the context and servlet using getServletContext() or getServletContext().getContext("/ViewsFlash") instead.

Where does the response go?
Normally, the viewsflash servlet writes to the response output stream. This can easily interfere with the application server's output stream, however. To solve this problem, the following parameters can be used with any query string. The most useful one is outputtorequestattribute. See Query String Reference below.

Can I use RequestDispatcher.forward()?
Yes. Use the code provided above under RequestDispatcher and use forward instead of include. Instead of outputtorequestattribute, use the appropriate options from Query String Reference. Of course, after the forward, no other code will be executed.

Query String Reference

Using HTTP queries

Command	Purpose
nooutputstream=1	Uses an already opened output stream, such as the JSPPrintWriter from a JSP page that includes output from the ViewsFlash application.
nooutputclose=1	Do not close the response output stream.
nooutputheaders=1	Do not set any headers in the output stream.
nooutputclose-1 and nooutputheaders=1 are often used together; they help make sure that the output stream is not closed prematurely and that response headers are not sent too soon.

outputtorequestattribute=attributename	Do not write to the output stream at all; write the content to the named request attribute using HttpServletRequest.setAttribute (). See also how to pass parameters.
outputtosessionattribute=attributename	Do not write to the output stream at all; write the content to the named session attribute using HttpSession.setAttribute ()
rediraftersetattribute=url	Redirect to an absolute URL afterwards
rediraftersetattribute=*?p=u	Redirect to the referring URL, set command tail parameter p to u. (See the Security page for the syntax).
outputtosessionattribute and rediraftersetattribute are often used together. The redirect goes to a dynamic page which retrieves the servlet's output from the specified session attribute.

stream=0 and &stream=1	If used, these must be at the very beginning of the query string. stream=0 forces reading the request parameters using getParameterNames(); stream=1 forces reading request parameters directly off the requests' input stream. The servlet parameter "servletrequestinputstream" controls this behavior; this provides a way to override it if necessary.

An HTTP query can be constructed by any application in any language, including Java, ASP, PHP, etc. The query is sent to the ViewsFlash application over the network using the standard HTTP protocol. ViewsFlash receives the query and sends its response in the appropriate content type, usually text/html. The application then interprets the query and uses the information as appropriate. Web Services API calls must use the TCP port specified in Application Security.

The remainder of this section provides sample code for popular languages. Port 8888 is used arbitrarily; there is no default port for the Web Services API. The example is the same as the one used in Using RequestDispatcher above.

String place = "Examples"; // the name of the Place
String apiparams = "cmd=getpollnames&status=open&spotname=" + place ; // cmd=getpollnames&spotname=Examples

Using Java in a different VM or server

String response = httpget ("http://yourserver.com:8888/ViewsFlash/servlet/viewsflash?cmd=getpollnames&status=open&spotname=Examples");

String httpget ( String fn ) {
try {
StringBuffer sb = new StringBuffer (500);
URL href = new URL (fn);
HttpURLConnection hc = (HttpURLConnection) href.openConnection();
hc.setRequestMethod ("GET");
hc.connect();

InputStream ins = hc.getInputStream();
int kar; char ch;
while ( (kar = ins.read () ) != -1 )
ch = (char) kar; sb.append(ch);
ins.close();

hc.disconnect();
return new String (sb);
}
catch (Exception e) {
return "\r\n";
}
}