-
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
IBM® WebSphere® sMash authentication is based on the Java Authentication and Authorization Service (JAAS), which allows various types of login modules to be added to the programming model without changing the authentication model.
-
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.
-
File-based user service
IBM® WebSphere® sMash provides a file based user service, a library that provides access to the user registry, as a
convenience for WebSphere sMash applications to leverage simple file based security.
-
LDAP user service
In addition to the default file based user service, IBM® WebSphere® sMash also provides
support for using an Lightweight Directory Access Protocol (LDAP) server as a user service.
-
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.
-
Working with HTTP or HTTPS services
A common use of the Connection API is to work with REST services over HTTP or HTTPS.
-
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 SPI 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.
-
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 and authorize events.
-
Extending token support
IBM® WebSphere® sMash's authentication provides a pluggable token handling framework to support custom token implementations.
-
Leveraging Trust Association Interceptors (TAIs)
Trust Association enables the integration of IBM® WebSphere® sMash security and third-party security servers. More specifically, a
reverse proxy server, such as IBM® Tivoli Access Manager - WebSEAL®, can act as a front-end authentication server while WebSphere sMash
applies its own authorization policy onto the resulting credentials passed by the proxy server.
-
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
-
Command line interface tasks
The command-line interface is the starting point for developing IBM® WebSphere® sMash modules.
-
Dependency management
This topic contains a reference about the dependency management support in IBM® WebSphere® sMash.
Dependency management allows a module to declare dependencies on other modules, and also ensures that
the correct revisions of those dependencies are used.
-
Module commands reference
This topic describes the commands that are always available through the command-line interface to all modules.
-
Extending the CLI
This topic contains information about extending the command-line by providing additional commands.
-
Creating a shared repository
This topic contains information about hosting a shared repository created with the command-line.
-
Trouble shooting the CLI
This article provides tips and workarounds when using the command-line interface.
-
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.
-
Using iWidgets with WebSphere sMash
Use the zero.iwidgets package to build and test iWidgets with IBM® WebSphere® sMash.
-
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)
The active content filtering (ACF) component removes potentially malicious active content from application content that is displayed in a browser.
-
Active content filtering
IBM® WebSphere® sMash provides support for removing and handling untrusted active content in requests and responses.
-
Active content filtering examples
The active content filtering (ACF) component removes potentially malicious active content from application content
that is displayed in a browser. This article explores situations in which active content can be leveraged to prevent
malicious content from running on the client.
-
Active Content Filtering: Default HTML filters
The zero.acf package provides a default active content filtering (ACF) HTML filter.
-
Active Content Filtering: Custom HTML filters
You can develop your own custom filter. Using the steps described in this article, you can create and use a new filter.
-
Protection against Cross-Site Request Forgery (CSRF) attacks
Cross-site request forgery (CSRF/XSRF) attacks are powerful and
straight-forward attacks that can totally subvert the security of Web
applications.
These attacks can target both the integrity (causing changes on the
server without users approval) and the confidentiality (leaking
private data) of Web applications.
-
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 to how the inetd daemon works on other operating systems. 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 the Assemble flow
IBM® WebSphere® sMash Assemble flow provides the capability to access different services and assemble them into a WebSphere sMash application.
-
Getting started with Assemble flow
This section is for Assemble flow beginners. It provides tutorials to help you to create a simple flow quickly.
-
Using flows
The functionality for constructing applications that produce feeds or conversational applications is provided through Assemble flow. This is an optimized and highly specialized flow engine for processing data feeds, and coordinating interactions with other services.
-
Flow activities
-
Flow programmatic API
Assemble flow provides programmatic API for accessing resources similar to flow activities.
-
Flow language reference
The flow language is a Web-based composition language made up of two main constructs: activities that define units of work and links that define dependencies between these activities.
-
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 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,
such as IBM® WebSphere® MQ or IBM WebSphere Application Server.
-
Configuring the connection to the JMS provider
The protocol extension for JMS requires that the application configuration defines
the necessary information to establish 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
In this example scenario, the protocol extension for JMS is used to communicate with
enterprise applications using either IBM® WebSphere® MQ or IBM WebSphere Application Server.
-
Connection "jms" protocol reference
The "jms" protocol allows an application to use the Connection API to send and
receive messages to and from destinations managed by 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
Files can be included from 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 IBM® WebSphere® sMash.
-
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
You can use PHP resources, like files, database connections and network sockets, in an extension.
Extensions can then create resource types and register with the runtime.
-
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
You can debug PHP Extensions written in Java™ using the debugging
features of Eclipse.
-
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.
-
Developer Web tools
The zero.core.webtools package provides a set of useful utility
functions for Zero application developers to use when building applications.
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
The employee Demo is a RESTful application that demonstrates many capabilities
of IBM® WebSphere® sMash. 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.
-
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.
-
Developing an iWidget application (zero.iwidgets.demo)
This tutorial walks you through building two separate iWidgets with IBM®
WebSphere® sMash, wiring them together, testing them, and then publishing those
iWidgets to IBM InfoSphere™ MashupHub.
-
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.
REFERENCES
-
API documentation