Creating Service Pages

1. Creating Services
2. Calling a Service and Formatting Results
3. Calling a Service if User Has Permission
4. Posting Data to a Service
5. Calling a Service from Javascript
6. Developing Service Pages using the Web Development Page

<xsl:template match="service">
  <svc op="displayPeople" sig="test.org.benow.service.TutorialSecureService.getPeople()"/>
</xsl:template>

<xsl:template match="displayPeople">
  1) The full result from <code>
     <a href="/svc/test.org.benow.service.TutorialSecureService">test.org.benow.service.TutorialSecureService.getPeople()</a></code>
     is wrapped by <code>displayPeople</code> and is:<br/>
     <textarea rows="20" cols="120"><xsl:copy-of select="."/></textarea>
     <br/>
  2) Without the page data, the <code>getPeople()</code> method <code>result</code> is<br/> 
     <textarea rows="20" cols="120"><xsl:copy-of select="result"/></textarea><p/>
  3) The following people are known:
     <div class="result">
     <xsl:for-each select="result/item">
       <xsl:sort select="last-name"/>
       <xsl:sort select="first-name"/>
       <xsl:value-of select="last-name"/>, <xsl:value-of select="first-name"/> 
       from <xsl:value-of select="address"/>, <xsl:value-of select="city"/> 
        <xsl:value-of select="postal"/><br/>
     </xsl:for-each>
     </div>
</xsl:template>

• has a root element of displayPeople, which causes the displayPeople template to be matched
• contains the same standard web state nodes as for page display, ie params, url, headers, session, etc. These can be useful for state management and display.
• has a result element which contains the XML representation of the result of the method call.

So, the XML produced by the method is reformatted to the desired output. This separation of processing and formatting is one of the strenghts of XSL, as the coders can focus on processing well (good java code) and presenting well (good html code)... the XSL merely reformats. The disadvantage is that things can get a bit messy. There's often quite a bit of XML produced by service methods and used as input to the matching templates. The XML produced by services can be seen in the XML browser by choosing the XML link in the top left of the page or hit the Alt-X shortcut (hold down alt, shift and x).

<xsl:template match="permissionedService">
  Calling <code>getPeopleOfHeight(Integer)</code> if <code><xsl:value-of select="java:getName($user)"/></code>
  has permission: <code>test.org.benow.service.TutorialService.invoke</code>
  <xsl:choose>
    <xsl:when test="java:hasPermission($user,'test.org.benow.service.TutorialService.invoke')">
      <svc op="displayPermissionedPeople" 
              sig="test.org.benow.service.TutorialSecureService.getPeopleOfHeight(Integer)">
        <heightInCM>180</heightInCM>
      </svc>
    </xsl:when>
    <xsl:otherwise>
      No <i>test.org.benow.service.TutorialService.invoke</i> permission 
      for <xsl:value-of select="java:getName($user)"/>
    </xsl:otherwise>
  </xsl:choose>
</xsl:template>

If the user has the test.org.benow.service.TutorialService.invoke permission then the services will be called to get known people over 180cm. The full signature of the method is used test.org.benow.service.TutorialSecureService.getPeopleOfHeight(Integer) with the parameter being passed in as named, heightInCM. The service invoker will take care of converting the given parameter string ('180') into the appropriate representation (an integer), and the service method will be invoked, returning the results. If the user does not have sufficient permission, a message will be displayed, instead of the service being invoked.

Using java:hasPermission($user,perm) can be useful to not display service results or links to service templates if the user does not have permission. In this way, the unpermissioned user is not even aware that extra functionality exists, which lessens the ability to discover things no of concern, and keeps the returned html cleaner. If a service is called to which the user has no permission, the service api will assert the permission and an error will be returned, which is ugly outside of debugging. Be reassured that if they do find out the existence of a service and method, they won't be able to invoke it if they do not have permission.

<form action="/svc/test.org.benow.service.TutorialSecureService" method="post">
    <input name="exec" type="hidden" value="addPerson(String,String,String,String,String,Integer)"/>
    <input name="redirect" type="hidden" value="?op=service"/>
    First Name: <input name="firstName"/><br/>
    Last Name: <input name="lastName"/><br/>
    Address: <input name="address"/><br/>
    City: <input name="city"/><br/>
    Postal: <input name="postal"/><br/>
    Height in CM: <input name="heightInCM"/><br/>
    <input class="buttonDefault" type="submit" value="Submit New Person"/>
</form>

When the service url is hit in this manner, the method is determined, the arguments are extracted and converted from string (when appropriate) and the method is invoked. After the method is invoked, the redirect url (if given) is redirected to. If no redirect parameter is given, the referring page is displayed again.

After values are supplied and the form posted, a new Person is added and the list of people is displayed via the template which matches service. You should see your added person at the bottom of the page.

In more advanced use cases, the parameters for complex objects can be specified as XML. The service handler will parse the XML into java objects before invoking the method. Files may also be posted to services methods with java.lang.File parameters using a multi-part form request. They will be received and stored temporarily and the method invoked.

Form submission provides an easy way to get stuff into the web application.

  <script src="/js/org.benow.util.Request.js">;</script>
  <script src="/js/org.benow.util.DOM.js">;</script>
  <script src="/svc/test.org.benow.service.TutorialSecureService.js">;</script>
  Minimum height of people to fetch
  <input id="height" size="4" type="text" value="180"/><br/>
  <input type="button" value="Fetch People By Height" 
     onClick="var height=document.getElementById('height').value; getPeopleOfHeight(height)"/>
  <input type="button" value="Fetch All People" onClick="getPeople()"/>
  <div id="response"/>

The javascript functions which receive and display the results are found in html/tutorial.js, which is automatically included at page delivery time.

function onGetPeople(url,http_request) {
	showPeople("getPeople()",http_request);
}

function onGetPeopleOfHeight(url,http_request) {
	showPeople("getPeopleOfHeight(int)",http_request);
}

function showPeople(method,httpRequest) {
	var result;
	alert('got xml from: '+method+'\n'+httpRequest.responseText);
	var items=responseXML.getElementsByTagName('person');
	if (items.length==0) 
		result='No people found.';
	else {
		result=items.length+' '+(items.length>1?'people':'person')+' found.<br/>';
		for (var i=0;i<items.length;i++) {
			var currE=items[i];
			var lastName=getChildText(currE,'last-name');
			var firstName=getChildText(currE,'first-name');
			var height=getChildText(currE,'height-inc-ms');
			result+=lastName+', '+firstName+' '+height+'cm<br/>';
		}
	}
			
	var respDiv=document.getElementById('response');
	respDiv.innerHTML=result;
}

The javascript interface to the services is quite refined. It is fast and very easy to use. The lessened overhead of implementing javascript ajax calls means that more time can be put into making things look and work well. It's less tedious, and easier to maintain than standard AJAX.