sfWebComponents

SmartFrog Web Components

Fixme (openoffice-common2forrest template)
The previous heading is more than one level below the heading before it. To remove this fixme, correct the structuring of your document.

The SmartFrog Web components provide a set of components for defining web applications (WAR applications), Enterprise (EAR) applications and Servlets for deployment onto a Java Application Server such as JBoss, WebLogic or Apache Geronmio, or a Java Web Server such as Jetty or Tomcat. It also includes a liveness page component, that can retrieve an HTTP page from a server as its liveness test, integrating web page visiblity with application liveness.

These components are still a work in progress, with the consequent warning that all interfaces and component descriptions are unstable. Furthermore, at some point in future, the components are likely to move to a self contained library, provisionally sf-www.jar.

The goal is to enable abstract descriptions of WAR, EAR and servlet applications which can then be deployed directly to any application server. To this end, the descriptions of application and web servers are abstract -they cannot be instantiated. A non-abstract implementation of the server component descriptions is needed to deploy WAR/EAR/Servlet applications.

At the time of writing, the sole implementation uses Jetty, in the separate sf-jetty component

Architecture

An ApplicationServer represents the web server or app server into which Web applications may be deployed. Different application server implementations extend this template to provide support for deploying such items. The specific types of deployable ApplicationServerContext are:

  • WAR file: a web application. All implementations should support this. Declared in a a WebApplication component.

  • EAR file: an Enterprise application, which requires a full J2EE system.

  • SAR file: (currently) JBoss specific service application.

  • Servlet Context: a context into which individual servlets can be declared. This is not as self contained as the others, but permits much more low-level configuration within SmartFrog deployment descriptors themselves, so eliminating much of the need for WAR file and web.xml configuration descriptor. Declared in a ServletContext component. Items that may be deployed within such a context must extend ServletContextComponent, the two standard options being Servlet and MimeType. These components have a context attribute that must be bound to the context into which they are to be deployed.

Other extensions of ApplicationServerContext may also be created and deployed into a server.

Every ApplicationServerContext must be bound to an ApplicationServer; this is done by setting the server attribute to a LAZY reference to the specific server.

When dynamically deploying applications to an application server, the full URL to the specific servlet, SOAP endpoint or other part of the system may be unknown until deployment time. For this reason, every component that can be deployed has an absolutePath attribute. This is set at run-time to the full path of the specific component.

Implementation

The ApplicationServer component is abstract; specific implementations are needed for every supported application server. These implementations provide implementation-specific classes to deploy components within the server. Each component that be deployed within an application server, and each servlet deployed within a SservletContext, must have a matching delegate class provided by the server-specific implementation. The portable components used in the deployment descriptors retrieve these delegate implementations from the server to which they are bound, and the heavy lifting of deployment is then delegated to the implementations.

The effect of this design is that one can describe WAR, EAR, SAR files and servlet applications within deployment descriptors, and deploy these applications to different application servers, merely binding them to different target systems.

Components

ApplicationServer

This is an abstract type that different application servers must extend/implement.

Table3
Attribute NameDescriptionOptional/Mandatory
supportsWARBoolean that indicates whether or not this server supports WAR files (i.e .Web applications)Mandatory
supportsServletContextBoolean that indicates whether or not this server supports servlet contextsMandatory
supportsEARBoolean that indicates whether or not this server supports EAR files.Mandatory
supportsSARBoolean that indicates whether or not this server supports SAR files.Mandatory

ApplicationServerContext

Base template/interface for anything that can be deployed into an application server

Table11
Attribute NameDescriptionOptional/Mandatory
serverLAZY reference to the server to which this context is boundMandatory

Run-time properties

Table12
Attribute NameDescription
absolutePathBase path of this context within the application server. This is the path exposed as part of the URL

WebApplication

Declares a web application

Table5
Attribute NameDescriptionOptional/Mandatory
contextPathContext Path for the web applicationMandatory
warFilePath of the web applicationMandatory
resourceIdResource id for the web applicationOptional
serverServer to which this web application is attachedMandatory

Run-time properties

Table10
Attribute NameDescription
absolutePathBase path of this context

ServletContext

Table6
Attribute NameDescriptionOptional/Mandatory
contextPathContext Path for the servlet contextMandatory
resourceBaseDirectory containing static files and JSP pages base for the servlet contextMandatory
serverServer to which this servlet context is attached Mandatory
classPathClasspath for the servlet contextOptional

Run-time properties

Table7
Attribute NameDescription
ipaddrIP Address of the context (currently determined from the network card/address that the SmartFrog daemon is listening on)
absolutePathBase path of this context

Servlet

Declares a servlet

Table2
Attribute NameDescriptionOptional/Mandatory
nameServlet nameMandatory
pathSpecPath specification: what URLs to bind to this servletMandatory
ClassNameClass name for the servletMandatory
initParamsVector of Initialisation parameters Optional
initOrderOrder for servlet initialisation. <0 means "on demand"; servlets with a value >0 are executed in orderOptional, default is -1
mappingsMappings (e.g. ["*.jsp","*.jspx"]Optional

Run-time properties

Table8
Attribute NameDescription
absolutePathBase path of this context. This is the concatenation of the servlet context which the servlet is deployed into with the servlet's pathSpec, with any trailing * stripped off the end of the latter. It is not valid for filename based mappings such as pathspec "*.do";

LivenessPage

The liveness page retrieves a web page on a liveness check. If the retrieval fails, an exception is thrown. This component is completely implemented in the services/www package.

LivenessPageSchema extends Schema {

//either

//full URL to the page

url extends OptionalString;

//or

//port of the page; default 80

port extends OptionalInteger;

//host of the page; default 127.0.0.1

host extends OptionalString;

//protocol, default http

protocol extends OptionalString;

//page

page extends OptionalString;

//query list of things that get turned into queries -without escaping.

queries extends OptionalVector;

//and any of

//flag to set if you want any error text fetched from

//the remote site. This is good for diagnostics.

fetchErrorText extends OptionalBoolean;

//response code below which the fetch is an error

minimumResponseCode extends OptionalInteger;

//error code above which an error has occurred,

//default is 299.

maximumResponseCode extends OptionalInteger;

//flag to follow redirects

followRedirects extends OptionalBoolean;

//check frequency. This is the number of pings between checks

//and so lets us probe less often than normal. default=1

checkFrequency extends OptionalInteger;

//flag to say that the check is on/off; useful during development

enabled extends OptionalBoolean;

}

The liveness page component does not deploy anything, but whenever a liveness check is made of it, it will attempt to synchronously download a page from the web server.

The component can either be configured with a full URL to a page, or by specifically configuring the hostname, port, protocol and page of a URL, along with an optional vector of query strings.

Note that "localhost" , "127.0.0.1" and the IPv6 equivalent "::1/128" all bind to loopback address of a system, not to any external interface of a server. As loopback interfaces are normally not firewall protected, probing for pages over the loopback address does not verify that a firewall is not interfering with remote access to a page. To verify that a page is remotely accessible, the best techniques are either deploy the checker to a remote host, or to relay the request via an HTTP proxy. This component uses the current proxy of the JVM, so will go via proxy if the JVM is so configured.

Table1
Attribute NameDescriptionOptional/Mandatory
urlComplete URL to retrieve. e.g. "http://smartfrog.org/"Mandatory unless page is set.
portPort to probe. Only used if url is not set.Optional-default=80
hostHost to probe. Only used if url is not set.Optional -default "127.0.0.1"
protocolProtocol to use -anything supported by java.net.URL is allowed. Only used if url is not set.Optional -default="http"
pagePage under a host to probe. Only used if url is not set.Mandatory unless url is set
queriesA vector of name-value pairs that are used to build a query string. For example, ["size","200","owner",LAZY owner"] could be turned into the query string"?size=200&owner=something", assuming that LAZY owner resolved to "something".There is currently NO ESCAPING of strings in this query.Optional, default=null
fetchErrorTextBoolean flag to indicate that the response text should be received when there is an error.Optional -default=true
These two values define the range of HTTP response codes that constitute a successful fetch. By default, the range 200<=299 is deemed a success
followRedirectsBoolean that controls whether redirects (3XX codes) should be followedOptional
checkFrequencyFrequency of checking the page; allows HTTP pages to be checked less often than other liveness pages. This is useful if the check is slow or CPU-intensive on the server.Optional -default=1
EnabledBoolean to enable/disable checkingOptional -default=true

Future enhancements, for which contributions are encouraged, include

asynchronous retrieval of pages

Post-download validation. This could be declaring a minimum size of a page, or a required mime type

XML validation and parsing of a downloaded document. At its most sophisticated, XPath expressions could be resolved against the downloaded content and turned into resolvable attributes. This would enable run-time extraction of content from XML messages.

POST support and url-forms-encoded encoding of the query string.

escaping of GET query parameters.

ServletContext Components

These are components that are only valid when bound to a servlet context.

MimeType

Declares a mime type within a servlet context. The mime type is removed when the application is undeployed.

Table9
Attribute NameDescriptionOptional/Mandatory
extensionExtension, e.g. "*.html"Mandatory
typeMime type, e.g. "text/html"Mandatory
contextReference to a servlet context e.g.LAZY PARENT:servletsMandatory