org.apache.tapestry.engine
Class ExternalService

java.lang.Object
  org.apache.tapestry.engine.AbstractService
      org.apache.tapestry.engine.ExternalService

All Implemented Interfaces:

IEngineService

public class ExternalService
extends AbstractService

The external service enables external applications to reference Tapestry pages via a URL. Pages which can be referenced by the external service must implement the IExternalPage interface. The external service enables the bookmarking of pages.

The external service may also be used by the Tapestry JSP taglibrary (ExternalURLTag and ExternalTag).

You can try and second guess the URL format used by Tapestry. The default URL format for the external service is:

http://localhost/app?service=external/[Page Name]&sp=[Param 0]&sp=[Param 1]...

For example to view the "ViewCustomer" page the service parameters 5056 (customer ID) and 309 (company ID) the external service URL would be:

http://localhost/myapp?service=external&context=ViewCustomer&sp=5056&sp=302

In this example external service will get a "ViewCustomer" page and invoke the IExternalPage.activateExternalPage(Object[], IRequestCycle) method with the parameters: Object[] { new Integer(5056), new Integer(302) }.

Note service parameters (sp) need to be prefixed by valid DataSqueezer adaptor char. These adaptor chars are automatically provided in URL's created by the buildGesture() method. However if you hand coded an external service URL you will need to ensure valid prefix chars are present.

Prefix char(s)	Mapped Java Type
TF	boolean
b	byte
c	char
d	double
-0123456789	integer
l	long
S	String
s	short
other chars	String without truncation of first char

A good rule of thumb is to keep the information encoded in the URL short and simple, and restrict it to just Strings and Integers. Integers can be encoded as-is. Prefixing all Strings with the letter 'S' will ensure that they are decoded properly. Again, this is only relevant if an IExternalPage is being referenced from static HTML or JSP and the URL must be assembled in user code ... when the URL is generated by Tapestry, it is automatically created with the correct prefixes and encodings (as with any other service).

Since:

2.2

Author:

Howard Lewis Ship, Malcolm Edgar

See Also:

IExternalPage, ExternalTag, ExternalURLTag

Constructor Summary

ExternalService()

Method Summary

ILink	getLink(IRequestCycle cycle, IComponent component, Object[] parameters) Builds a URL for a service.
String	getName() Returns the name of the service.
void	service(IEngineServiceView engine, IRequestCycle cycle, ResponseOutputStream output) Perform the service, interpreting the URL (from the HttpServletRequest) responding appropriately, and rendering a result page.

Methods inherited from class org.apache.tapestry.engine.AbstractService

constructLink, getParameters, getServiceContext

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ExternalService

public ExternalService()

Method Detail

getLink

public ILink getLink(IRequestCycle cycle,
                     IComponent component,
                     Object[] parameters)

Builds a URL for a service. This is performed during the rendering phase of one request cycle and bulds URLs that will invoke activity in a subsequent request cycle.

Parameters:

cycle - Defines the request cycle being processed.

component - The component requesting the URL. Generally, the service context is established from the component.

parameters - Additional parameters specific to the component requesting the EngineServiceLink.

Returns:

The URL for the service. The URL always be encoded when it is returned.

service

public void service(IEngineServiceView engine,
                    IRequestCycle cycle,
                    ResponseOutputStream output)
             throws ServletException,
                    IOException

Description copied from interface: IEngineService

Perform the service, interpreting the URL (from the HttpServletRequest) responding appropriately, and rendering a result page.

Parameters:

engine - a view of the IEngine with additional methods needed by services

cycle - the incoming request

output - stream to which output should ultimately be directed

Throws:

ServletException

IOException

See Also:

IEngine.service(org.apache.tapestry.request.RequestContext)

getName

public String getName()

Description copied from interface: IEngineService

Returns the name of the service.