A NEW TODAY IS DAWNING!

Tutorial: Building a Web Application

Posted Fri, 02 Apr 2010 - 02:55 by admin


Introduction

This tutorial is an extension of the Tutorial: Building a Web Service.

Once the example Web Service is up an running it can be accessed from a web browser.


The Basics

A BuildProfessional Web Service is an application that receives a Request document in XML format and based on the contents of the request, issues a Reply document in XML format. While every request and reply is XML format they can contain simple text structures (such as an ASCII file or web page).

A default BuildProfessional installation contains configurations to extract HTML content from the Web-API reply to surface a web application.


Prerequisites

You will need the following to host a web application:

Accessing the Web Service from a Browser

Provided you have successfully built the Web Service example, enter the following URL in a browser:

http://localhost/bpcgi/webapi.pl?s=bpwsc&e=bpwsSignIn

Login with the user "guest" and test other entry points.

Modify the bpwsQuick function to alter the reply page. Remember to restart the Web-API Manager after making code changes.


How Does it Work?

Each of the entry points in the bpws component package provide HTML formatted replies and it is a little web application in itself. This allows the entry points to be accessed from a web browser. This works essentially like the a normal web service with some extensions:

When a request comes from a web browser the *FORMAT is "HTML" by default.

As requests are processed in the entrypoint function (e.g. bpwsQuick), an HTML reply is returned.

To access secure entry points (bpwsMain) we use a SignIn entry point to obtain user creditials. The session id is then returned as a temporary cookie which the browser returns on subsequent requests.

When you enter a URL in the browser, the web server receives it and sends it to the webapi.pl perl script. The perl script parses the URL, creates a Web-API envelope and call the Web-API Client to process the request.

You can force the reply to XML format even if you are accessing a URL (browser) interface. Simply add "&format=XML" to the end of the URL as the following examples illustrate:

http://localhost/bpcgi/webapi.pl?s=bpwsc&e=bpwsQuick&format=HTML

http://localhost/bpcgi/webapi.pl?s=bpwsc&e=bpwsQuick&format=XML

Most of the entry points (bpwsSignIn, bpwsTest, and bpwsMain) use XSL Transformations to create HTML formatted replies. The logic process is then to first get all the data required for the entry point in XML format. If that's what the caller wanted, then issue the reply. If the caller wants HTML, we transform the XML into HTML (or XHTML). This method, while simplified has several advantages:

  • A single entry point could serve several uses. For example an entry point that returns part details for an part number could return XML if it was called by another program or it could return HTML if called from a browser.
     
  • An entry point could use many different transformations on the same entry point to display different results. For example, one user might want five columns of information, while another wants seven. Or you may want two different sort or rows groupings. This is all handled by the transformation rather than the entry point itself.
     
  • An entry point could use different transformations to return different XML results by removing or adding data.

NOTE. XSLT code is stored as blob components.

 

Troubleshooting

There are several files to look for potential problems:

  • A web server is required to access the application. Test it with http://localhost/bpweb
     
  • Perl is required for access to the application. Test is with http://localhost/bpcgi/hello.pl
     
  • The Web Service must be running. Test it with Developer Request Tester.
     
  • installdir / tmp / webapimanager.log contains errors relating to bad configurations or missing programs.
     
  • installdir / tmp / myapp_err.txt contains any error messages and trace output from the application. The "-D" option in the Command Line above is to turn trace output on.
     
  • installdir / tmp / bp_myapp.log contains log messages from the bpws components (from function bpwsLog).