Developer's Guide

  • Overview of concepts
    This part of the Developer's Guide provides an overview of the basic concepts that form the programming model for building IBM® WebSphere® sMash applications. It includes an overview of the conventions and configuration for WebSphere sMash applications.
    • IBM WebSphere sMash concepts
      IBM® WebSphere® sMash has an event-driven architecture and utilizes Representational State Transfer (REST) concepts that are reflected in its programming model. This section describes how to build Groovy, PHP, or Java™ based handlers. It also describes the application directory layout and the concept of virtualized directories that allow seamless integration of the application with its dependencies.
      • Global context
        The global context, as the name implies, provides a central construct for applications to store and retrieve environment information.
      • Global context reference
        The following reference tables show the defined paths to available attributes in the global context zones.
      • Event processing
        IBM® WebSphere® sMash applications can define, fire and handle events to interact with the various handlers within the WebSphere sMash platform.
      • Application directory layout
        IBM® WebSphere® sMash applications have a particular layout for their directory structure. This layout provides both organization around the parts that make up your application and convention around how your application works.
      • Virtual directories
        IBM® WebSphere® sMash uses a dependency management utility called Ivy to ensure that your module is using the right versions of the libraries you declare as dependencies. In Ivy, these libraries are called modules, and they are located through a process called dependency resolution. See the section on Dependency Management for more information. WebSphere sMash provides seamless integration of script directories across an application and its dependencies, while maintaining each as separate entities.
      • Security considerations
        IBM® WebSphere® sMash implements system-level authentication and authorization. Applications can take advantage of WebSphere sMash security by defining security rules that determine which resources are protected, and how they are protected.
        • Authentication
        • OpenID authentication
          OpenID consumer based authentication provides end users with a single digital identity that they can use across the internet. It proves that an end user owns an identity URL without externalizing their password or email address.
        • Security tokens
          IBM® WebSphere® sMash authentication provides the pluggable token support for various types of security tokens.
        • User service
          User service is a library that provides access to user registries.
    • Writing Java handlers
      Java™ can be used to implement handlers within IBM® WebSphere® sMash applications.
    • Writing Groovy handlers
      Groovy can be used to implement handlers within IBM® WebSphere® sMash applications.
    • Writing PHP handlers
      PHP can be used to implement handlers within IBM® WebSphere® sMash applications.
    • Accessing global context
      The global context is available from all parts of a IBM® WebSphere® sMash application. How you access the global context varies depending on the language of the artifact.
    • Configuration
      You can specify the properties and behavior of a IBM® WebSphere® sMash application in configuration files.
    • Resource (REST) programming model and conventions
      IBM® WebSphere® sMash simplifies the task of creating applications using the Representational State Transfer (REST) architectural style.
    • JSON support
      The zero.core package includes support for JavaScript Object Notation (JSON) data structures.
    • File serving
      Static files, scripts, templates, and directory listings can be invoked and served directly out of the public folder. Files that implement REST conventions should instead be placed in the app/resources folder.
    • Response rendering
      An HTTP response body can be generated using direct APIs or indirect rendering. In either case, you should set status and headers before writing any output.
    • URIUtils APIs
      URIUtils is a set of APIs for constructing relative and absolute URIs within an IBM® WebSphere® sMash application. These APIs are helpful when constructing URIs for many purposes, including hyperlinks, images, and CSS links.
    • Calling a remote resource
      The connection infrastructure in zero.core provides a simple way to make REST-style requests to resources using a variety of protocols.
      • Using the Connection API
        Use the Connection API to send a request to a remote resource using the connection infrastructure and obtain a response.
      • Sending an e-mail using EmailConnection
        The EmailConnection class provides a simple way to send an e-mail, including an e-mail that contain attachments, in IBM® WebSphere® sMash applications.
      • Configuring destinations
        Use a destination configuration to specify how interactions with a resource made using the Connection API are handled.
      • Configuring protocols
        Requests that are made using the Connection API have a collection of protocol configuration properties associated with them. The protocol configuration properties are used to send the request to the resource.
      • Configuring connection handlers
        A connection handler is a small piece of logic that you can configure for a destination. The connection infrastructure invokes a configured connection handler before sending a request, and again when receiving the response.
      • Creating a connection handler
        Use the Handler interface to create a new connection handler.
      • Simple logging connection handlers
        Two logging connection handlers are included with the connection infrastructure. The handlers are designed for simple scenarios and as aids to problem determination when using the Connection API to work with a remote service.
      • Creating a custom protocol transport
        This topic describes how to write a custom protocol implementation which can be used with the Connection API.
      • Protocol reference
        This section describes the default set of protocols that can be used with the Connection API.
        • HTTP and HTTPS protocols
          These protocols communicate with remote resources using HTTP or HTTPS.
        • SMTP protocol
          This protocol sends an email with optional attachments.
        • File protocol
          This protocol allows the application to read or write a file on the local filing system.
        • FTP protocol
          This protocol allows the application to read or write a file using the file transfer protocol (ftp).
        • Event protocol
          This protocol allows a connection destination to be implemented by local handler for the transmit event.
    • Firing events
      Events, in the IBM® WebSphere® sMash platform, organize loosely coupled handlers. Although this feature is not generally required for most application developers, it enables advanced developers to build custom extensions to WebSphere sMash.
    • Extending global context
      You can extend the global context with additional zone and type handlers. Zone handlers store the data and are responsible for scope and lifetime of that data. Type handlers handle value "pathing".
    • Global context commands
      The global context can be used to store behavior by associating commands with global context keys.
    • Validators and validation
      Caching in HTTP gains improved efficiency through validation mechanisms, including entity tags (Etags) and last-modified dates. This section describes the high-level support for validation available in IBM® WebSphere® sMash. Within WebSphere sMash, static-file serving supports ETags and caching.
    • Nested resources in IBM WebSphere sMash
      WebSphere sMash provides configuration access to nested resources.
    • HTTP error handling
      When problems occur on a Web site, error pages should be returned to the client. You can use the rendering capabilities to provide custom error pages.
    • Extending security
      IBM® WebSphere® sMash security leverages the flexible event-based system to make it easy to add your own security implementations. With this enhanced flexibility, you can implement your own request processing event handler for secure, authenticate and authorize events as well as registering preauthenticate handlers for security related tasks that do not fit neatly with the authenticate and authorize events.
    • Extending token support
      IBM® WebSphere® sMash's authentication provides a pluggable token handling framework to support custom token implementations.
    • Deprecated security functions
      This topic describes the features that have been deprecated in IBM® WebSphere® sMash security.
    • Leveraging Trust Association Interceptors (TAIs)
    • Extending user service
      The IBM® WebSphere® sMash user service leverages the Global Context to make it easy to add your own user service implementation.
    • Leveraging XOREncoding
      IBM® WebSphere® sMash provides an XOREncoder library with a simple encoding API so applications do not have to store passwords in clear text. Depending on whether your library supports encoding of a property in zero.config, you can use the command line or Eclipse to encode the password using XOREncoding.
    • XML encoder utility
      XMLEncoder is a utility class for XML entity encoding. This utility can be used to escape parts of the response that may have untrusted active content.
    • HTTP configuration
      HTTP is the main method through which applications receive requests. The following section describes how to configure HTTP for a IBM® WebSphere® sMash application.
    • SSL configuration
      This topic describes how to how to configure an IBM® WebSphere® sMash application to accept requests from clients using HTTPS.
    • JVM configuration
      IBM® WebSphere® sMash Applications can be tuned by adjusting the JVM configuration
    • Proxy configuration
      You can configure an Apache Web server as a reverse proxy server for routing to multiple IBM® WebSphere® sMash applications. This allows multiple WebSphere sMash applications to be accessed using a namespace at a single Web server address.
    • Troubleshooting Core
      Consult this documentation to troubleshoot problems starting and running an IBM® WebSphere® sMash application
    • API Documentation
  • Using iWidgets with WebSphere sMash
    Use the zero.iwidgets package to build and test iWidgets with IBM® WebSphere® sMash.
  • Command line interface tasks
    The zero.cli.tasks extension provides the base tasks available through the command line interface (CLI). The CLI tasks are split up the following categories: module tasks, module group tasks, and repository tasks.
  • Getting started with database access
    Data access has use cases that range from very simple to very complex. zero.data provides an easy-to-use data access interface to get to your data. zero.data is an API that is flexible enough to handle complex situations without making simple tasks cumbersome.
  • Zero Resource Model overview
    The Zero Resource Model (ZRM) provides a simplified way to create RESTful resource handlers with a data store. Developers need provide only simple "model" definitions of resources; ZRM uses the model definitions to create the data store and support full create/read/update/delete semantics. In addition, ZRM supports a variety of content formats, including JSON and Atom Publishing Protocols.
    • Zero Resource Model quick start tutorial
      This tutorial provides a brief introduction to the Zero Resource Model and illustrates how quickly you can get up and running with RESTful data.
    • Zero Resource Model CLI tasks
      The zero.resource component contributes several Command Line Interface (CLI) tasks for the lifecycle development of Zero Resource Model (ZRM) data models.
    • Configuring the Zero Resource Model
      An application using the Zero Resource Model consists of the database configuration, resource model declaration, and the resource event handler.
    • Zero Resource Model declaration
      The resource model is the single, definitive source of metadata about your data. It contains declarations about the essential fields and behaviors of the data in your application.
    • Zero Resource Model API
      The Model API accesses resources programmatically using collection-like constructs.
    • Zero Resource Model HTTP REST API
      When a model has been declared, HTTP REST access to your modeled resources can be enabled in just one simple step. This document shows how to enable the HTTP REST API for your declared resource models and shows how the Model API and queries are performed in HTTP.
    • Using Dojo with the Zero Resource Model
      The Zero Resource Model has a Dojo client that makes it quite simple to interact with RESTful data from JavaScript and Dojo widgets.
    • Troubleshooting the Zero Resource Model
      Known issues and workarounds to troubleshoot the Zero Resource Model.
  • Client programming with Dojo
    IBM® WebSphere® sMash includes the Dojo Toolkit for developing AJAX-based clients. Although AJAX and Dojo are not required for WebSphere sMash applications, the combination can result in compelling Web applications.
  • Client-side secure mashup programming
    IBM® WebSphere® sMash includes the secure mashup provider for the Open Ajax Hub for developing secure client side mashup applications.
  • Active content filtering (ACF) overview
    The active content filtering (ACF) component removes potentially malicious active content from application content that is displayed in a browser.
  • Atom support
    Project Zero provides Atom support both implicitly and explicitly. This article describes the explicit support that is available in the zero.atom extension.
  • Runtime management
    All IBM® WebSphere® sMash applications include the necessary components to allow a running server to be managed and to manage other WebSphere sMash applications. Examples of some of the types of management functions all applications have embedded within them include starting, stopping, recycling, monitoring, statistics and configuring other applications.
    • IBM WebSphere sMash management tasks reference
      This topic contains an alphabetical list of the management commands that can be performed on any WebSphere sMash application. To issue these commands, your working directory should be the root directory of the application, or any directory below the root directory of the application.
    • Zero socket opener (ZSO) management extensions
      The Zero socket opener (ZSO) extension enables the Java™ runtime that is hosting a IBM® WebSphere® sMash application to be started on demand when a client connects to the application. The ZSO works in a similar way. It opens a listening socket and when a client connects to that listening port the WebSphere sMash application associated with that port is started to accept the connection.
    • Deployment recommendations
      Before deploying a IBM® WebSphere® sMash application into production, there are several steps that are recommended to secure and protect your application.
  • Using RSS support
    Use the zero.rss package to publish and consume RSS feeds with IBM® WebSphere® sMash.
  • Using the Assemble flow
    IBM® WebSphere® sMash Assemble flow provides the capability to access different services and assemble them into a WebSphere sMash application.
  • Assemble flow management
    Assemble flow management provides features for accessing flow definition files and monitoring flow instance status, including a REST style API for managing flow definition files and a Web based interface to list runtime information of flow instances.
  • REST to SOAP extension
    The REST to SOAP extension, zero.connection.soap, enables a REST-style request to an external SOAP service using the Connection API.
  • Protocol extension for JMS
    The protocol extension for JMS, zero.connection.jms, allows the application to use the Connection API to send and receive messages to and from destinations managed by an external Java™ Message Service (JMS) provider.
    • Connection protocol reference
      This topic describes the Connection API protocol implementation which allows an application to send and receive messages to and from destinations managed by an external Java™ Message Service (JMS) provider.
    • Configuring connections to the external provider
      This topic describes the configuration of connections to an external Java™ Message Service (JMS) provider.
    • Working with javax.jms.Message objects
      The zero.connection.jms dependency includes a TypeHandler implementation for working with javax.jms.Message instances in the global context. The type handler allows applications to use the GlobalContext or Connection APIs to read the contents of the message without using the javax.jms.Message APIs directly.
    • An example scenario using the protocol extension for JMS
      This topic outlines how to configure a simple application to communicate with an external Java™ Message Service (JMS) provider.
  • Timer service
    The timer service allows tasks to be scheduled to execute repeatedly on a fixed delay.
  • Kicker service
    The kicker service "kicks" a RESTful endpoint to make it aware of some information or change. It does this using an HTTP POST and passes the relevant information in the form of a form-encoded POST body or as a string of the content type of your choice (for example a JSON string).
  • File kicker and receiver
    This topic describes the file kicker and receiver components that allow an application to be notified of changes to a specified file or directory.
  • PHP support
    IBM® WebSphere® sMash enables developers to build applications in the PHP programming language.
    • PHP conventions in IBM WebSphere sMash
      The articles in this section review some of the common conventions used when building an application in PHP.
      • XML handling in PHP
        The Extensible Markup Language (XML) is a general purpose markup language that is commonly used to transfer data/information between two cooperating entities such as applications, servers or clients. The PHP support in IBM® WebSphere® sMash supports rendering PHP variables as XML and manipulation of XML strings as PHP variables.
      • Libraries and dependency resolution
        Explains how to include files from Ivy dependencies.
      • PHP string encoding
        This section describes important information about the handling of PHP strings in IBM® WebSphere® sMash.
      • PHP setlocale
        This section describes the use of the PHP setlocale function.
      • PHP to Java bridge
        This article describes how to access Java™ classes from PHP using the PHP to Java bridge. The following sections provide a description of the bridge and examples of using it.
    • PHP Language support
      A summary of the PHP language support provided in IBM® WebSphere® sMash.
      • Core PHP functions
        This section lists the PHP library functions and shows which PHP functions are currently supported by Project Zero.
      • Php.ini configuration
        A number of configuration directives are supported in the config/php.ini file which can be set to alter the behavior when executing PHP scripts.
      • PHP Superglobals
        PHP supports the concept of auto globals or superglobals. These are variables that are available in any scope and are described in detail at PHP.NET superglobals documentation. The PHP support in IBM® WebSphere® sMash enables a subset of these superglobals for use by PHP script developers.
    • Debugging PHP scripts
      The instructions on this page explain how to debug PHP scripts running inside a IBM® WebSphere® sMash application.
    • Extending PHP
      IBM® WebSphere® sMash application developers can choose to build extensions to PHP that provide access to functionality that was built using Java™. This guide summarizes the steps for creating such an extension to the platform. For the purpose of this guide, it is assumed that the developer uses the Eclipse development environment to build the extension.
      • Creating a simple PHP extension
        Use the following steps to create a sample extension that allows manipulation of BigDecimals.
      • Passing variables to a PHP extension by reference
        Any variable can be passed to a PHP extension by reference. This differs from Java™ where scalar types and object references are always passed by value. This tutorial extends the big decimal extension by adding a new extension function that negates the value passed. The negated value is passed by reference.
      • Sending output to the browser
        The PHP runtime provides an output stream for sending data back to the browser. This tutorial shows how to access the output stream and write data into it. The output stream is provided as a Java™ PrintStream object.
      • Accessing variables in the runtime
        The PHP runtime allows an extension to create, read, update and delete local, global and super global variables. This tutorial extends the big decimal extension to add an extension function that accesses global variables. The function checks whether a global variable exists, and if it does, whether it contains a string that can be converted into a BigDecimal.
      • Configuring an extension
        The PHP runtime allows an extension to load configuration information that is stored in php.ini. This tutorial shows how to get configuration information at runtime. It extends the big decimal extension by adding a new extension function that does division of BigDecimal values.
      • Parsing function arguments
        This tutorial shows how to parse arguments passed to an extension function.
      • Raising runtime errors
        Errors and warnings are easy to raise in the PHP runtime. This tutorial shows how to raise an error by passing a ResourceBundle that contains the error message to the PHP runtime.
      • Calling functions in the runtime
        The PHP runtime allows an extension to invoke functions in the runtime. The functions can be other extension functions or script defined functions. This tutorial shows how to invoke the var_dump function in the runtime and pass it an argument by value.
      • Accessing PHP arrays in an extension
        The PHP runtime allows an extension to receive an Array as a parameter and provides several interfaces to access and update the elements of that array. New arrays can also be created. This tutorial shows how to create an extension function which takes two arrays as parameters and returns an array containing the bigdecimal sum of elements in the two arrays which have the same integer key. Elements without integer keys or with keys which do not appear in the other array are ignored.
      • Using PHP resources in an extension
        PHP Resources include files, database connections and network sockets. Extensions are free to create their own resource types and register with the runtime. A resource can store any kind of Java™ object, in the example below, the big decimal extension creates a resource to store an instance of a Java BigDecimal class.
      • Registering for object callbacks
        This example shows how a Java™ extension can implement the XAPIObjectCallbacks interface. This interface connects a Java extension to one or more objects in the PHP runtime. The Java extension is called back when events it has registered for are invoked on the object. The example shown below registers a class called Lookup with the PHP runtime. This class is registered with an array of XAPIObjectCallbackType that the extension is interested in (read dimension, write dimension, is dimension set and unset dimension).
      • Debugging a PHP extension in Eclipse
        PHP Extensions written in Java™ can be debugged using the debugging features of Eclipse. Create a single Project Zero PHP Application project which contains both the extension to be debugged and the PHP script which invokes it. Start the project using the Debug as->Project Zero Application option. Place breakpoints and then invoke the script from a web browser.
      • Conversion of types between PHP and Java
        Explains how PHP types are converted to and from Java™ Types by XAPI.
      • Overview of PHP runtime services
        There are many services that the runtime provides to PHP extensions, including: Error configuration and reporting. Invoking functions and methods in the runtime. Access to local/global/super global variables. Defining read only constant values. Writing output to the browser/console window. Access to the environment (such as the current working directory). Registering classes and creating object instances. Obtaining configuration information.
      • Source code for the big decimal extension
        Here is the source code for all the tutorials in one file.
    • Troubleshooting
      This article provides some of the common issues with getting your applications to work as designed.
    • XAPI Documentation
    • P8 Documentation
    • API Documention
  • Developer Web tools
    The zero.core.webtools package provides a set of useful utility functions for Zero application developers to use when building applications.
  • Unit tests
    This topic describes the zero test command and patterns for writing JUnit test cases for IBM® WebSphere® sMash modules.

  • SAMPLES

  • Developing a data-to-Web application (zero.suggest.demo)
    This section provides tutorials that introduce the Zero Resource Model (ZRM) and the JavaScript library that make it easy to read and write data from a Web browser.
  • Employee demo
    Employee Demo is a RESTful application that demonstrates many of IBM® WebSphere® sMash's capabilities. It provides an interface for managing employee data, including listing, creating, editing and deleting employee records.
  • PHP employee demo
    The Employee Demo is a RESTful application developed using the PHP programming language that demonstrates many of IBM® WebSphere® sMash's capabilities. It provides an interface for managing employee , including listing, creating, editing and deleting employee records.
  • Zero Resource Model demo
    The Zero Resource Model (ZRM) demo (employee.resource.demo) is a simple project that illustrates the Zero Resource Model and the Dojo Data API JavaScript™ implementation that makes it easy to read and write data from a Web browser.
  • Using the flow samples
    There are some basic flow samples that you can install and use to verify your flow runtime installation, and to demonstrate a few of the basic features of the flow language. The flow augmented employee demo sample demonstrates the addition of work flow to the employee.demo.
  • Atom application (books.demo)
    This sample demonstrates Atom support with the zero.atom extension and ibm_atom Dojo extension. zero.atom is useful for explicit Atom support.
  • OpenID demo application
    This application demonstrates various features of IBM® WebSphere® sMash Security and illustrates how to leverage OpenID authentication, how to define security rules for the application, and how to extend a user registry.
  • Office Monitor demo: A Rich PHP application
    The Office Monitor is a situational mashup application developed in PHP to demonstrate RESTful principles and wiring multiple RESTful resources to rich DOJO constructs such as Drag and Drop and context menus.
  • Open AJAX client side mashup application
    This application demonstrates some of the features of the Open AJAX 1.1 Hub provider (Secure mashup) capabilities.

Version 1.1.0.0.21442