RegisterLog In to Jazz.net dW
Download 4.0.6 Release
February 28, 2014

Jazz Foundation

The foundation of the Collaborative Lifecycle Management solution

Jazz Foundation 3.0

Product Release Trial | November 23, 2010
This is not the most recent version. We recommend Jazz Foundation 4.0.6 . This is made available for archival purposes and may contain bugs and/or security vulnerabilities. If you do download this version, it is being provided AS IS, without warranties of any kind, including the implied warranties of merchantability and fitness for a particular purpose. We strongly advise you review the support pages for this version and update the product or take actions recommended therein. Security bulletins contain instructions for the security vulnerability addressed therein, and may require upgrading to a newer version. Link to security vulnerability blog: IBM PSIRT blog.

Jazz Foundation 3.0 News

Jazz Foundation 3.0 - New and Noteworthy

Here are some of the more noteworthy items appearing in the Jazz Foundation 3.0 release (November 23, 2010) which is now available for download. Note that some of the items listed here may be included in Jazz Foundation 1.0.0.x and are repeated for completeness.

Repository

Create database tables from setup wizard

The Jazz Team Server setup wizard now provides administrators a simple way to detect and create the Jazz database tables from the Web UI. Once you have setup a valid database connection, the server checks to see if the tables exist. If they don't, you can choose to create them directly from the setup wizard without the need to run repotools.

Create Tables Step
Click for full-size image

OAuth consumer keys for pre-authorized users

Associating a pre-authorized user with a consumer key allows requests to be made by this user without additional authorization. Applications use this capability to run background administrative tasks, such as send e-mail notifications, without user intervention. Pre-authorized users can be associated with a consumer key programmatically. The OAuth Consumer Management page in the Admin UI also supports the management of consumer key properties by allowing the name, secret, pre-authorized user, and trusted values to be edited. Edit OAuth Consumer Key
Click for full-size image

Time-limited Client Access Licenses

It's now possible to build Client Access License keys with expiration dates that are independent of the server expiration. These time-limited Client Access License keys can be used to make extra product features available on a trial basis, even on a purchased (non-expiring) server. Any new Client Access License keys created can include an expiration date (existing product keys are unaffected).

Expiring Client Access License
Click for full-size image

Public URL configuration in setup wizard

The Jazz Team Server setup wizard now includes a step to configure a public URL for the server. The server generates absolute URLs, typically known as "Public URLs", to resources used in mail notifications, feeds, for copying to the system clipboard, for Web access, and for stable resource identification across Rational products. These generated URLs may be referenced in contexts that are outside of the local network in which clients typically access the server (say, outside of your corporate firewall). This configuration property provides an alternate or "public" hostname/authority for use in these type of situations.

Public URI Configuration
Click for full-size image

Repotools commands for user management

The following commands have been added or enhanced in the repotools utility:

repotools -archiveUser
Archives an existing user.
Usage: repotools -archiveUser userid=testUser

repotools -exportUsers
Exports the list of users. The user records are exported into a csv file. The user id, name, email address, group membership and licenses assigned to the user are exported into the csv file.
Usage : repotools -exportUsers toFile=users.csv

repotools -importUsers
Imports the list of users into the database. If the user already exists in the database, the user record is updated with the information provided in the import file.
Usage : repotools -importUsers fromFile=users.csv

repotools -syncUsers
Syncs the user records with the user information in the LDAP directory. This command performs the same operation as the LDAP nightly sync task.
Usage : repotools -syncUsers

Case insensitive logins

Case insensitive logins can now optionally be allowed. Some users of jazz have login ID's that are in mixed case form but prefer to login in all lower case. If the application server's authentication method allows case insensitive logins then it's now possible to make the Jazz application accept them as well. Allowing case insensitive logins can be enabled through the "Use case insensitive user ID matching" property on the Advanced Properties page of the admin Web UI. The default is unchanged; administrators must explicitly override this property to enable case insensitive login.

JazzProjectAdmins repository group

A new repository group is available to grant project area and process template management privileges. Using this group lets an administrator reduce the number of users who must be granted scary JazzAdmins privileges. JazzProjectAdmins are allowed create and manipulate project areas, and create and deploy process templates. JazzProjectAdmins are not allowed to manage users or edit the server configuration.

JazzProjectAdmins

Migration note: configurations that do not contain any settings for JazzProjectAdmins will continue to work as normal. No migration or modification of configuration settings is required.

If you are using LDAP, define a new LDAP group that maps to this role. If you are using custom LDAP group mappings, also edit the property "Jazz to LDAP Group Mapping " in the Advanced Properties page of the Admin Web UI.

If you are using tomcat-users, the role should be available to you for edit in the user editor.

Changes to AbstractService

AbstractService now includes a preferred method for composing Repository URIs that are to be returned to the calling client: getRequestRepositoryURL(). This method constructs the base URL using the hostname specified by the request.

The default behavior of getRepositoryURL() (deprecated as of 2.0.0.1) is now to also return the request hostname (configurable via system properties - "on" by default) - causing it to behave effectively the same as getRequestRepositoryURL(). This change supports the assertion that the requesting client's hostname is the right hostname to return to the client when constructing URIs that are returned to the source, and that the canonicalized hostname is not the best option in this case.

AbstractService also includes getLocalServerURL() which also returns the URL of the repository that this service is bound to. The distinction is that the hostname and port of the URI is that of the IP interface on which the request was received. Thus the URL can be used as a prefix in constructing a server URL that the server can use to refer back to itself, e.g. when making a local network call.

See work items 101047 and 88625 for additional information.

Model Evolution

The repository now supports the evolution of models. Components can modify their models in certain ways without requiring a full import/export migration and still maintain compatibility with older clients. The repotools addTables command has been enhanced to handle the database modifications for these models. See wiki topic https://jazz.net/wiki/bin/view/Main/ModelEvolution for a description of allowed model evolutions and the impact of supporting older clients.

Server Query Service

There is now a server-side query available to server component developers. It uses a simple iterator style interface for the results instead of the pagination style interface of the client-side query and the new service does not cache either the queries or their results thus avoiding the cache eviction issue. See work item 46491 for more details on the issues. The service is called IServerQueryService and supports an almost identical API to the IQueryService.

New AST Query API

There is now an API _keyExists(IString key) on all state extensions to determine whether item has a an extension of that type has an extension of that name. The string and medium string state extensions now support a _like and _ignoreCaseLike API that behave in the same way as the existing API. See work items 78904 and 94675.

JDBC Connection "Keep Alive"

The repository now has a configurable service that tickles database connections that have been setting idle for a period of time in order to avoid having idle connections closed by a server and then exceptions thrown when those connections are used. The two configurable properties are to turn on the service and to set the length of time to touch an idle connection. These can be set from the admin web UI. See work item 94097.

Token based licensing support

The floating license service now has support for token based licensing. The support includes an extensible mechanism which allows for multiple token service providers to be made available for use. Additionally, each license token service provider may provide an extensible UI widget to be used in the configuration of the service. A system administrator can configure the floating license server to use one of the available providers. The license token service provider is responsible for token checkin/checkout. Reporting has also been expanded to include token usage reporting as well.

Additionally, a Jazz Team Server can be used as a token provider. If a token-enabled floating license is installed, the floating licenses can consume tokens from a Jazz Team Server that has been configured to provide tokens.

Server-side query service

The server-side query service which was introduced in the last release now supports an optimized path for query result processing. If a query is executed inside of a transaction, the query results can be read directly from the DB on demand rather than copying the entire result into memory. This should improve the runtime and memory performance of large queries both by allowing the consumer of the query to control how much data they wish to read and to avoid unnecessary copying of the that data. If the server-side query service is invoked outside of a transaction then the behavior is the same as before. See work item 46491 for a discussion of the issues. To take advantage of this feature component developers can place their queries within a transaction and then use the iteration API.

Clustering API

In order for the Foundation server, and products based on Foundation, to be clusterable, all of the code inside of the products needs to work correctly in a cluster. A new service, com.ibm.team.repository.service.IDistributedOperationService, has been added in Repository to make clustering easier for component developers. That new service exposes data structures that can be used to store data in memory in a cluster-aware way. Components with existing services should review the clustering guidelines as a starting point to ensure that their code will execute correctly in a cluster.

Reusable MessageBox widget

There is a new Jazz UI widget available called the MessageBox that brings a common user experience for page-level message handling and display across our UIs. The widget is capable of displaying four different types of messages, detailed messages including stack traces, and message IDs included with the message. The API for this widget, including examples, is outlined in the MessageBox documentation.

Success Message

Error Message

Warning Message

Using DB2 with reduced authority

It's now possible to setup a Jazz server using DB2 so that a user with DBADM authority is only required to run repotools -addTables; the remaining steps can be done as a user without any special privileges. Running with reduced privileges allows for better separation and security when multiple databases are installed in the same DB2 install. To see more details about the setup, you can visit the ReducedDB2Privileges wiki page.

New services discovery story

The discovery service is a new mechanism for locating services provided by both the Jazz Team Server and affiliated applications. When an applications is registered with the Jazz Team Server as a member of its Jazz application group, any services the application offers will be noted by the Jazz Team Server and made available via a new discovery service. Services are grouped into "types", which can have any number of properties (such as the location URLs of individual service endpoints). The discovery service is used to retrieve information about service types, without having to know which applications offer the services. The Application SDK includes a new library which makes it easy to use the discovery service from a Java application, and a sample which illustrates its usage.

See the Jazz Discovery Story wiki topic for an overview of the new mechanism and links to more detailed information. Further refinements of the story and its implementation are expected in subsequent milestones.

Register new applications

A new "Registered Applications" page allows the administrator to register new applications with the Jazz Team Server:

Registered Applications

OAuth consumers registration improvements

There are two improvements to the OAuth consumer registration page. It's now possible to register an OAuth consumer using a public RSA key as the secret, and to enter a consumer key to be used for the consumer rather than let the provider generate one. Both improvements were implemented to enable the server to be configured to accept requests from OpenSocial containers who use public key secrets and static consumer keys.

Foundation license packaging

The Jazz Team Server now has it's own license keys, and the structure of the licenses has changed. In the past, there was a server license that controlled the trial period, and the CAL keys were trials when the server key was a trial. Now, the server key is always permanent but the individual CAL keys have trial expiration dates associated with them. This change means that a single server can be used to have a mix of permanent keys and trial keys for different products. A new CAL key was also created that enables only the Foundation capability - however, the name and/or details of this key will likely change in the future. This new key is the only key included with the Foundation server by default. Each product should contribute product specific CALs to the server as they are installed. Refer to the Foundation30LicensePackaging wiki page for more details.

Redesigned Jazz Team Server setup wizard

The Jazz Team Server setup wizard has been updated to use the new vertical step list. This "Table of Contents" design will become increasingly important as we add steps to the setup wizard in the future.

Redesigned Setup Wizard

Registered applications enhancements

The Registered Applications page now includes support for a pre-authorized user when adding the application. This user is automatically associated with the generated consumer key for the application. When registering an application, you should check the application's documentation to decide if a pre-authorized user is required.

Add Application Dialog

Common user administration

Applications built on the 0.6 SDK (e.g, CCM, QM) that configure a Jazz Team Server are subscribed to user synchronization and common user administration. The application will also share the external user registry (e.g., LDAP properties) configured for the JTS, for the purpose of importing users and displaying user roles in the user editor. The external registry properties are excluded from the admin web UI of the application.

Setup documentation is available at the UserSynchronization wiki topic.

Common license administration

Applications now will be subscribed to common license administration when they are connected to a Jazz Team Server. The license administration UI will be excluded from the web UI of the application, and all license installation must be managed in the JTS. License checks performed by the application will continue to work as expected, by proxying from the application to the JTS. License assignments can still be viewed and edited from the user editor of the application.

Shared mail configuration

Applications now will be subscribed to a common mail service when they are connected to a Jazz Team Server. The mail configuration is excluded from the admin web UI of the application.

Admin web UI enhancements for applications

The Admin Web UI has been customized for applications. The new property "Jazz Team Server Location" has been added to show which Jazz Team Server the application is connected to. Additionally, a few of the Server pages that are not relevant to applications have been removed from the left navigation. This provides administrators of applications with a streamlined and intuitive experience.

Server Status Page - Fronting Application

Automatic diagnosis of repotools application problems

For some time the repotools application has reported installed bundles that fail to become resolved. Such bundles are invalid and indicate a development-time or runtime provisioning problem. The latest version of the repotools application diagnoses why each bundle failed to become resolved. For example:

CRJAZ1218I The bundle "com.ibm.team.jfs.app.discovery" with the id 55 is invalid, it is not "RESOLVED".    
 file:/build/build-areas/RJF-Repository/T/RJF-Repository-T20100611-0718/repository-test-server/stage/server/conf/..
      /update-site1/plugins/com.ibm.team.jfs.app.discovery_1.0.0.v20100607_2244.jar [55]
   Direct constraints which are unresolved:
     Missing imported package com.ibm.team.jfs.app.util_0.0.0.
   Leaf constraints in the dependency chain which are unresolved: 
     file:/build/build-areas/RJF-Repository/T/RJF-Repository-T20100611-0718/repository-test-server/stage/server/conf/..
	    /update-site1/plugins/com.ibm.team.jfs.app.util_1.0.1.v20100611_1434.jar [66]
       Missing required bundle org.eclipse.osgi.util_0.0.0.  

In this entirely hypothetical example the bundle com.ibm.team.jfs.app.discovery failed to become resolved since it cannot import the package com.ibm.team.jfs.app.util. The package is missing and should have been exported by the bundle com.ibm.team.jfs.app.util but was not exported because the bundle failed to be resolved due to its required bundle org.eclipse.osgi.util being absent.

License contributions from applications

Applications in the application group can now contribute license keys to the JTS by implementing and exposing a service in the application's Service Contribution Resource. This feature makes packaging application's license keys easier, because license keys can be packaged with the application rather than manually added to the JTS. It also makes the the management of licenses in the JTS more flexible to changes in the application groups, because the JTS will automatically detect license keys contributed by applications when they are added to the group. For more details about how to expose license keys through the Application's SCR see the ApplicationLicenseKeyContributions WIKI page.

License key enhancements

Many enhancements have been made to the license key policy definition so that various licensing strategies can be handled by Jazz license keys. These new types of key can now be created:

  • Keys with a term license - Now non-trial keys can have an expiration date.
  • Keys with manual trial activations - Now the trial period can be started when the server admin is ready, rather than automatically on install.
  • Multiple keys can be merged into a single license type - Now separate license key purchases can be merged together as a single type for assignment.

You can find more details about how to create keys with those new features by reading the LicenseKeyCreation wiki page.

New registered applications step in server Setup wizard

A new step has been added to the Jazz Team Server Setup Wizard. The Registered Applications step provides a way to scan the installation directory to discover applications that can be registered with the Team Server.

Detected Installed Applications

After the scan completes, a list of installed applications is presented to the user who can modify the default values and create a pre-authorized user. The administrator can then register these applications with the Jazz Team Server.

Modify Application Suggestions

Contributed application setup steps

There were significant improvements made to enhance the setup of applications. The setup wizard now supports contributed steps which get embedded into the setup wizard via iFrames. Once an application is registered with the Jazz Team Server, the server checks to see if the application is contributing any steps to the wizard. If it is, these steps are dynamically added to the step list. The adminstrator can now complete the setup for each application; all from a single setup URL.

Contributed Wizard Steps

For more information about the CLM Workbench Automated Setup initiative, please see our wiki topic.

LDAP enhancements for Tomcat

The Setup User Registry step of the setup wizard now provides the ability to save modified variants of the Tomcat server configuration (server.xml) file, and web-app deployment descriptor (web.xml) files for LDAP configuration. The modifications are based on the settings supplied during setup. These files can then be copied to replace the original files to enable LDAP authentication. This avoids the need for manual editing and helps prevent mistakes.

LDAP Enhancements

New URL Whitelist Configuration page in Server Administration

The Jazz Team Server - Server Administration web page contains a new entry for configuring the Foundation Web UI proxy's URL whitelist. This allows for configuring cross-site communications from a Jazz Team Server to a site that is not a Jazz Team Server or registered application. In previous releases, there was an undocumented ability to modify the application's web.xml to specify the whitelist; that mechanism was unsupported and has been removed.

Proxy Configuration UI

Jazz Team Server Administration Home page

A new "Home" page has been added to the Admin UI of the Jazz Team Server. This page will serve as a landing page for all of the administration links throughout the Jazz Team Server and registered applications. From this page, an administrator will be able to access the Server Administration, User Administration, Lifecycle Project Administration, and the administration pages provided by each application. This page helps to simplify the task of administering a complex installation by providing a central view for the administrator.

Jazz Team Server Administration Home

Team Process

Project linking improvements

The project linking UI has been simplified. In addition, nested service provider catalogs are now supported (such as those used by ClearQuest).

Project linking

Web UI hovers

Rich hovers are now implemented in the web UI for users, project areas, and team areas (using their Jazz compact rendering documents).

Web UI hovers

Timeline and iteration management in web UI

Timelines and iterations can now be managed in the web UI. Check out the Timelines tab in the project area editor.

Iteration management

Non-admin access to project area and process template management admin pages

Access to the project area and process template management pages using the https://host:port/jazz/admin URL is now available to all users. Previously, only members of the JazzAdmins repository group could access the pages.

Process Admin Management

Permissions tab redesign

The project area Permissions tab in the web UI has been redesigned to show the configuration tree and the permissions side by side on the same tab. The configuration nodes are now also decorated with the same icons and text as the Eclipse client.

Process Permissions

Configurable start/end times of timelines and iterations

You can now set the start and end time of a timeline or iteration. The date and time is displayed and edited in the client's time zone, but the iteration ends at the same moment in time in all time zones. For example, if an iteration ends at 5PM Pacific time, then it ends at 8PM Eastern time.

Iteration end time

Non-leaf iterations can be set as current

Both the web and Eclipse client now support setting a non-leaf iteration as the current iteration for a timeline.

Non-leaf current iteration in the Web Client

Project area hovers and the Project Areas list page in the web client now include linked project areas.

Project Links in the Project Areas list page.

Project Links in a Project Area hover.

To enable OSLC/CM - OSLC/CM linking, we introduced a new project link type "Related To". An OSLC/CM service provider, such as an RTC project area, can link to one or more other OSLC/CM service providers.

Related to link type in Web Client

Project area update framework

We've added extensible support for updating project areas with changes made to canned process templates. For example, if new work item types are added to the Scrum template, the Project Area Updater will be able to add those new work item types to project areas created with older versions of Scrum.

This action is available by right-clicking on a project area in the Team Organization view and selecting "Add New Features".

It's important to note that this feature is contribution-driven, meaning it will only have an impact once higher-level products have adopted this framework.

Application API to declare operations

Applications can now declare process-enabled operations by including the appropriate entry in their root services document. Operations declared this way will be available for configuration in the JTS's project area editor and these operations can be queried via the Process Security REST Service.

This enhancement removes the requirement for applications to install any bundles on the JTS in order to have process-enabled security. For more details, please see the Process Security REST Service API.

Updating in operation report REST API

Client operations can be now supported by the operation report REST API. A new "isProjectOperation" query parameter is used to tell the operation report service if the operation is a project operation. This parameter should be included in the service url with value "true" when the operation is a project operation, and "false" (or omitted) for a team operation. For more details, please see the Process Security REST Service API.

Application-scoped process context visibility

A new feature has been added in support of application-scoped process context visibility. With this feature, project areas and process templates created by applications of the JTS will by owned by the creating application. This means that each application will see only its own project areas and process templates when querying.

Multi-resource configuration data is now also application scoped. That is, the application will only see the configuration data types that it defines.

Project area management web UI for applications

Process now provides an embeddable project area management web UI. Applications can embed this web UI in their application to expose project area management to their users. Any project areas created in this embedded UI will be owned by the embedding application, as discussed in the section above.

Embedded project management

Process template management web UI for applications

The JTS now provides a preliminary version of embeddable process template management web UI. Applications can embed this web UI in their application to expose process template management to their users. Any process templates created in this embedded UI will be owned by the embedding application.

Embedded template management

Support project area initialization service

A mechanism has been added to notify applications on successful creation of project areas. Applications that want to be notified when project areas are created can do so by exposing a project area initialization service in their root services document. The root services entry is named jp:projectAreaInitService and the initialization service URL is provided as the value of the rdf:resource attribute. For more details and datamodel, please see the Notify ProjectArea Initialization Service.

Sharable process

To make it easier to administer many projects in a uniform way, the Process component now allows project areas to share their process. This allows administrators to create and configure a central project and have the process consumed by client areas. Project areas that consume the process will inherit roles and role assignments, configuration of permissions, operation behavior and preconditions, and configuration data from the project area that is providing the process.

To share the process of a project area, select the "Allow other project areas to use this project area's process" button in the Project Area Editor:

Sharing a project area's process

To consume a shared process, select the "Use the process from another project area for this project area" button in the Project Area Editor and select the process using the "Change" button:

Consuming a project area's process

New feed entries for process

New process-related feed entries are now generated for:

  • modifications to the access control list in a project area
  • adding or removing a service provider to/from the service providers list in a project area
  • modification to the role assignments in a project area or team area

New REST API in process admin service

New REST APIs have been added to process admin service:

  • Project Admin collection REST API is used to retrieve the project administrators. For more details, please see the Process Admin REST Service API.
  • Read Access List REST API is used to retrieve the users in the read access list of a project area. For more details, please see the Process Admin REST Service API.

Configuration data can be finalized from process configuration UI

Configuration data can now be marked as final from the Process Configuration tab of a project area or team area editor. In the previous release, the final flag had to be added by editing the source; now the flag will be added if the "Final (ignore customization in child areas)" checkbox is checked.

Checkbox in Process Configuration

Process enabled components that provide a UI for editing Configuration Data will need to adopt this change for the checkbox to appear. Details are in work item 122711.

Access to new project areas limited to team members by default

Project areas are now created so that they are visible only to members of the project, its teams and project area administrators. To make a project area visible to others, use the controls on the Access Control tab of the project area editor in the Eclipse client or the Web client.

Access Control tab of the web client

Access Control tab of the Eclipse client

Foundation Web UI

Cross-server dashboards

Dashboards can now contain viewlets from any number of other Jazz servers, allowing you to track activity from several servers on a single dashboard. The viewlet chooser will allow you to select viewlets on other servers (ones your server administrator has configured as friends of your server).

Widget catalog

The Widget Catalog is the next generation replacement for the Viewlet Chooser and is designed to improve the way users discover, browse and add viewlets to the dashboard.

Widget Catalog

OpenSocial Gadget support

Users now have the ability to add external OpenSocial Gadgets to the dashboard using the Widget Catalog.

Widget Catalog Gadget Support

Gadget Example

IBM iWidget support

Users now have the ability to add external IBM iWidgets to the dashboard using the Widget Catalog.

Widget Catalog iWidget Support

iWidget Example

Component menus

Jazz web applications now have the ability to specify component menus for navigation bar page links. These menus can be used to provide quick access to high-level queries, saved searches, recently viewed resources and much more.

Component Menus

Pagination control

A Pagination Control for navigating paged content is now available for use within Jazz web UIs.

Pagination Control

Integrated HTML viewlet source view

The HTML Viewlet now uses an integrated source view that automatically pretty prints HTML source, and provides a Full Screen mode to maximize screen real estate when editing.

HTML Viewlet

Headlines viewlet rich text editor support

The Headlines Viewlet now uses a rich text editor to edit the headline body text. All of the editing features found in the HTML Viewlet are now available in this viewlet as well.

Headlines Viewlet

Improved developer experience

Server startup times have been drastically reduced. Server restarts are no longer required when changing JavaScript dependencies or adding new JavaScript, and there is no longer any need to disable or clear your browser's cache when changing JavaScript or CSS during development.

Reduced JavaScript footprint

The JavaScript footprint for applications using the Foundation Web UI has been significantly down-sized, reducing both download and startup times for application page loads, and generally improving the user experience.

Mini Dashboard

A new sidebar that contains a single column dashboard has been added to the web UI. The contents of Mini Dashboard always remains consistent as you navigate between web UI contexts.

Mini Dashboard

The search box in the nav bar has been improved to provide user assistance when the user focuses the search area. In addition, there are new APIs to support advanced search options and the ability to display results inline in the search area.

Improved Search

Home menu

Cross-server project navigation has been greatly improved with the addition of the home menu to the Jazz banner. Implemented using component menu APIs, the menu consolidates a list of projects from all of your server's friends into a unified view.

Home menu

Browser support widget

A new widget is available for providing various levels of feedback to users with unsupported web browsers. Unsupported browsers that are known to be broken (such as IE6 or Firefox 2) will be interrupted with a pop-up message, whereas other unsupported browsers will only receive a subtle message in the footer. jazz.util.browserSupport exposes API for customizing and querying the list of supported/unsupported browsers.

Browser Support Widget

ResourceLink widget now supports OSLC UI Previews

The jazz.ui.ResourceLink widget now supports the new OSLC UI Previews specification in addition to the legacy Jazz Compact Rendering specification.

Jazz Foundation Services

Status of baseline creation

A GET /jazz/baselines/ now provides status on the pending baseline activity. In particular, it can be used to monitor the progress of the asynchronous creation of the historical index for a given baseline.

Alternatively, when posting a baseline request or description, the service will now also return a Last-Modified response header, which can be used to condition a subsequent query or search on the completion of the historical index for this baseline.

Constraining queries in a baseline

In order to simplify writing a SPARQL query for the historical RDF index, the Foundation now provides an extra query argument (baseline=<baseline-url>) to constrain the query inside a particular baseline (or comma separated list of baselines), without requiring to write a complex SPARQL query for that. This is especially useful when multiple complementary graphs participate in an index about the same resource, and the query writer doesn't know the exact graph boundaries (see item for more details). This mechanism allows you to write once a SQARQL query against the live RDF index and then apply it with no modification to the historical index for a baseline.

Text search in a baseline

The historical index is now eligible for full-text search (in addition to SPARQL query). A historical full-text search can be performed using GET /jazz/search?historical.q=....

Improved baseline management

The creation of a baseline now requires admin user privileges. Additionally, when a baseline is deleted (via DELETE /jazz/baselines/<baseline-id>), the historical index will be purged from the relevant information. Note that a deletion from the index is not instantaneous, and will be dealt with asynchronously. The baseline status resource can be used to monitor progress on index deletion. Finally, baseline descriptions are now indexed into the live index (in addition to their content being indexed in historical index). Therefore one can both query (SPARQL) or search (Lucene) for baseline description data (e.g. find all the baselines which have ever been created).

Baseline for owned resources

A baseline request can now also select resources using their project resource context using the request parameter: jazz:resource-context. This can be particularly useful in scoping a baseline to only those resources owned by a set of security contexts.

Reindexing a baseline

A reindex operation can now also apply to a baseline, by including it using <jazz:inBaseline rdf:resource="<baseline-url>"/>. This will cause the corresponding historical index to be recreated entirely. Note that a reindex request may either apply to the live index, and optionally select certain storage areas; or apply to the historical index, and explicitly include certain baselines; but the same reindex request cannot apply to both live and historical index (separate requests would instead need to be issued).

Scoped reindexing for text search

The text indexing service is now able to honor a reindex request scoped to certain storage areas. In the past, it used to fully reindex the text index store; now it will only reindex the selected subset (similar to RDF indexing support).

Resource location in RDF index

The list of built-in system properties included by default for each resource has been augmented with the resource storage location, allowing mapping a frontside-URI to the corresponding storage-URI via the property <https://jazz.net/xmlns/foundation/1.0/resource-location>. Also note that the RDF graph for a given resource is also named with the resource storage-URI. Hence the new resource-location property can conveniently be used to avoid writing graph queries (which become quite complex when multiple complementary graphs participate to an index for the same resource). The complete list of system properties is thus:

  • <http://purl.org/dc/terms/isPartOf> <storageArea frontside URL>
  • <http://purl.org/dc/terms/contributor><URL of user performing the last modification>
  • <http://purl.org/dc/terms/creator><URL of user creating the resource>
  • <http://purl.org/dc/terms/created> <UTC timestamp of initial creation>
  • <http://purl.org/dc/terms/modified> <UTC timestamp of last modification>
  • <http://purl.org/dc/terms/format> <string denoting MIME content-type>
  • <https://jazz.net/xmlns/foundation/1.0/etag> <string representing the resource HTTP ETag>
  • <https://jazz.net/xmlns/foundation/1.0/resource-location> <storage URL of the resource>
  • <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <URL of the root element property in XML or RDF/XML>

X-Last-Modified-XSD header

The Foundation introduced a new timestamp header in HTTP responses, providing millisecond precision, where the standard Last-Modified only offers precision to the second. The new response header is named X-Last-Modified-XSD and is supplied on storage operations, reindex requests, baseline operations and indexing status requests. The format is XSD UTC time ((yyyy-MM-dd'T'HH:mm:ss.SSS'Z') and can be conveniently reused directly in SPARQL queries without needing any further processing.

Required authorization header

The Foundation now requires that both full-text search and RDF queries need an "Authorization" header that will scope the results of the text query to a given application. Only resources contained in a storage area of the application will be returned.

Discontinued /jazz/text-indexing-rules

The old JRS /jazz/text-indexing-rules service has been discontinued. It has been replaced by the text indexing rule resources defined at https://jazz.net/wiki/bin/view/Main/JFSXmlTextRules.

RDF index store now based on Jena

The Foundation server now uses a different RDF index store based on the Jena implementation. Even though clients have no direct access to the index store, it could still have some impact for clients upgrading an already populated repository. In this case, the repository would contain old (Tyto) indexes. In order to move forward, such customers would have to explicitly trigger a full reindexing of their resources (see https://jazz.net/wiki/bin/view/Main/JFSReindexingAPI). The old Tyto data will still remain in the database, and become obsolete (would have to be manually purged to recover the space - but would have no impact anyway).

Clients taking a fresh new repository (or recreating one using repotools -createTables) would not be affected in any way.

<Namespace> tag deprecated

The terminology in the Storage API has changed: "storage area" is the new name for what was called a "namespace". As a consequence, the corresponding XML definition was upgraded to use the XML root element <StorageArea> in place of <Namespace>. Clients should convert to the new form. In short term, the Foundation will still tolerate the old XML definition for a storage area; but it is likely to be discontinued.

Storage area access control

In previous releases it was possible to create a storage area without specifying an application consumer key. In this release it is no longer possible to create a storage area without an application consumer key, by default. More information can be found in the JFS Core Security and JFS Storage API wiki topics.

Also, access control is now enforced on query, by default. Also, query requests can specify the contexts they would like to query within. More information on the query service can be found in the Foundation Query Services wiki topic.

Query Service pagination

SPARQL query results are now paginated. More details can be found in the JFS Query Results Pagination wiki topic.

Support for synchronizing resources

The Storage API has been enhanced to allow an admin account to impersonate as a different user, for the purpose of synchronizing resources from external systems. Previously any change would always have a modification stamp from the authenticated user, which in the sync case was a functional ID. The API specification is available here. The StorageServiceSyncTests class (com.ibm.team.jfs.storage.tests package) shows example usage.

Indexing decimal values from XML content into RDFs

The XML indexer is now able to extract decimal values into RDF literals of type xsd:decimal (e.g. "1.300"^^xsd:decimal). The list of data types supported by XML indexing rules now includes {string, int, boolean, date, uri, decimal}.

Example of an indexing rule in RDF/XML format for extracting a decimal price from XML:

<jfs:IndexSpecification xmlns:jfs="https://jazz.net/xmlns/foundation/1.0/"
     xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
     jfs:namespace="http://foo.bar"
     jfs:onlyForType="application/x-foobar+xml"
     rdf:about="">
   <jfs:index>
     <jfs:Property jfs:anchor="//price" jfs:object="." jfs:objectType="decimal" />
   </jfs:index>
</jfs:IndexSpecification>

RDF Turtle syntax now supported

The RDF Turtle format is now recognized by JFS for resources associated with either MIME type text/turtle or application/x-turtle. The Turtle syntax can also be used to define custom indexing rules for XML contents provided that the containing resource is associated with the MIME type application/com.ibm.team.foundation.indexer+turtle. Similar to other indexing rules in alternate RDF formats (RDF/XML, N-Triples), indexing rules expressed in Turtle can also be queried in SPARQL.

Example of an indexing rule in Turtle format for extracting both title and date from XML:

@prefix jfs: <https://jazz.net/xmlns/foundation/1.0/> .
<>   a   jfs:IndexSpecification ;
     jfs:index
         [ a jfs:Property ;
           jfs:anchor "//title"
         ] ;
     jfs:index
         [ a jfs:Property ;
           jfs:anchor "//date" ;
           jfs:object "." ;
           jfs:objectType "date"
         ] ;
     jfs:namespace "http://music.example.com/schema" ;
     jfs:onlyForType "application/x-com.ibm.examples.music+xml" .

Note: When using the Turtle syntax, the current base URI is implicitly denoting the frontside URL of the containing resource in storage.

Much improved scalability

The Foundation Indexing Service is now able to digest huge resources in a scalable fashion. The theoretical limit now matches the practical limitation of 1GB content in storage.

Additionally, there is no limit to the size of query/search results being paginated through any longer. Indeed, the implementation was reworked to avoid accumulating these in precious server memory.

And finally, the Query Service is performing much faster, especially on complex SPARQL queries involving the OPTIONAL graph pattern. Our measurements show a better than 10x improvement on complex queries like:

PREFIX wrapper: <https://jazz.net/xmlns/alm/rm/Reference/v0.1#>
PREFIX nav: <http://foo.bar/nav/>
PREFIX dc: <http://purl.org/dc/terms/>
PREFIX jfs: <https://jazz.net/xmlns/foundation/1.0/>
SELECT ?rsc ?created ?modified ?creator ?contextid ?tag 
       ?contrib ?name ?parent ?ref ?format ?formatPred
WHERE {
  ?rsc nav:parent <https://front.side/rdm/folders/folder1> .
  ?rsc dc:isPartOf <https://front.side/rdm/resources> .
  OPTIONAL { ?rsc nav:tag ?tag} .
  OPTIONAL { ?rsc wrapper:reference ?ref } .
  ?rsc dc:created ?created ; dc:modified ?modified ; dc:creator ?creator .
  ?rsc jfs:resourceContextId ?contextid ; dc:contributor ?contrib ; nav:parent ?parent .
  ?rsc ?formatPred ?format .
  FILTER ( ?formatPred = dc:format || ?formatPred = wrapper:contentType )
}

Accurate resource timestamps in indexing status

The status for the Foundation Indexing Service has been augmented to include an accurate timestamp in XSD format (UTCZ). Each indexer will provide an extra element in the status resource:

<jazz:lastProcessedXSD rdf:datatype="http://www.w3.org/2001/XMLSchema#dateTime">
   2009-12-07T10:32:04.035Z
</jazz:lastProcessedXSD>

The XSD timestamp provides millisecond precision (as opposed to HTTP time which is rounded to the second) and can be conveniently injected into a SPARQL query or a baseline creation request.

Support for bulk operations

There is now preliminary support for performing bulk requests on the Jazz Foundation server using a single HTTP POST request. This support allows a client to POST multiple HTTP requests to the server using multipart-MIME format with the responses from each request returned to the client in multipart-MIME format. More information can be found in JFSBulkOperations

Support for tracking changes

There is now preliminary support for atomic commit of multiple resource changes in the storage service using the new changes service. This support provides an API for creating change resources, performing storage operations within a change sandbox, and committing or rolling back the resource changes. Commit is performed as an atomic operation. More details on the current support can be found in JFS2StorageChangeAPI.

More details on the ideas, discussion and direction of change within the Jazz Foundation can be found in JFS2ChangeModel.

More text document formats indexed

The indexing support for textual resources has been improved to support more commonly used file formats. The following formats are now supported:

OASIS Open Document Format (OpenOffice.org)
File Type Content-Type
*.odt application/vnd.oasis.opendocument.text
*.ods application/vnd.oasis.opendocument.spreadsheet
*.odp application/vnd.oasis.opendocument.presentation
Office Open Xml (Microsoft)
File Type Content-Type
*.docx application/vnd.openxmlformats-officedocument.wordprocessingml.document
*.xlsx application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
*.pptx application/vnd.openxmlformats-officedocument.presentationml.presentation
Rich Text Format (Microsoft)
File Type Content-Type
*.rtf application/rtf or text/rtf

Indexing rules for RDF

It is now possible to exclude certain resources from text indexing and to exclude certain RDF properties from triple indexing and text indexing. More details can be found in the JFSXmlTextRules and JFSRdfIndexingRules specifications.

Reindexing a node in a cluster

It is now possible to reindex a single Jazz Foundation server node in a cluster environment. For more details, please see JFSServerReindexing

Using Jena ARQ extension for SPARQL

Support has been added for experimenting with the more advanced query capabilities provided by the Jena ARQ query syntax. The ARQ syntax is a superset of the standard SPARQL syntax, with support for advanced features, such as aggregate functions.

This support is experimental and is being provided to gather feedback from early adopters. ARQ is not a part of the SPARQL standard sytnax and is not portable to other SPARQL providers. This support is subject to change or removal. Feedback on this support is encouraged in Enhancement 106450.

The ARQ syntax can be requested on a query by supplying the "syntax" query argument with the value "ARQ". For example: /jazz/query?syntax=ARQ&q=SELECT+*+WHERE+{+?s+?p+?o+.+}

The following query illustrates the count aggregate function provided by ARQ and counts the number of attachments in pending tasks.

PREFIX task: <http://foo.bar/tasks/>
SELECT ?uri count ( ?attachment )
WHERE {
     ?uri <task:attachment> ?attachment .
     ?uri task:status "PENDING" .
} GROUP BY ?uri

More information on the ARQ syntax and its extensions to SPARQL can be found at Jena's web site. More information on the future of the SPARQL specification can be found on the SPARQL 1.1 Working Group site. Finally, more information on the query service can be found in JFSIndexStoreQueryAPI

Getting server current time

The current server time can be retrieved via an HTTP HEAD request to the indexing service. For example: HEAD /jazz/indexing

An HTTP HEAD request to the indexing service will return two headers containing the server time in different formats. First, the Last-Modified header will contain the server time in standard HTTP header format (see HTTP 1.1 Last Modified Header and HTTP 1.1 Date/Time Formats). Also, the X-Last-Modified-XSD header will contain the server time in XSD format (see XML Schema Date and Time Formats).

More information on the indexing status resource provided by the indexing service can be found in JFSReindexingAPI > Status Resource.

Design patterns for JFS applications

The Jazz Foundation has begun gathering and recording the design and implementation patterns we see recurring in fronting applications. These patterns are currently captured in JazzFoundation Resource Design Concerns

The following topics are included:

Foundation services are cluster-ready

The Foundation Core Services now operate correctly in a clustered environment, and will behave in a consistent manner regardless of which node in the cluster processes an individual request. The one exception is that pagination through query results relies on load balancer session affinity to find the next results page.

In a clustered setup, each node in the cluster maintains its own copy of an index. The overall indexing progress can be tracked by accessing the page at <server-url>/jazz/indexing where <server-url> is either the URL of the cluster itself or that of a specific node. The former aggregates indexing status from all the nodes into a single result.

More information on configuring a JTS cluster can be found on the DeployingJazzInCluster wiki page.

Indexing enhancements

A storage area may now specify that its contained resources should not be indexed, or only indexed for text or RDF. Here is an example of a storage area with indexing turned off:

<StorageArea
  xmlns="https://jazz.net/xmlns/foundation/1.0/"
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
  rdf:about="">
  <rdfs:label>Non-queriable Data</rdfs:label>
  <frontsideURL>https://jazz.net:443/jazz/data</frontsideURL>
  <indexer>none</indexer>
</StorageArea>

Additionally, the index data extracted from a storage area can be made public such that all applications may query over the data. By default, all index data from the resources in a storage area is private to the application that owns the storage area. A storage area may declare its indexed data to be public or private by setting the <indexMode> element.

More information is available on the JFSStorageAPI wiki page.

Transactions on storage

A prototype implementation of JFS3StorageTransactions is included in this release. This style of atomic update to the storage service is intended for short bursts of interactions with the storage service. Long running interactions, such as change sets which can be shared and reviewed over time, should look toward the JFS2StorageChangeAPI.

Compacting the RDF Index

There are certain situations where the Jena TBD index can grow larger than expected, especially when there is aggressive updating of a single resource. Please see Bug 106920 for more details.

To alleviate this problem, we've added a new repotools command for compacting the TDB index. The command-line syntax is:

{repotools.bat} -compacttdb srcdir={location of TDB index} 
    [tempdir={location to store temporary files during compaction}]

Note that you must either shutdown the server or suspend indexing before running this command.

Using Jena SPARQL 1.1 extensions

Support has been added for experimenting with the more advanced query capabilities provided by the Jena SPARQL 1.1 query syntax. Similar to the ARQ extension unveiled in 3.0M5, it is a superset of the standard SPARQL syntax, with support for advanced features, such as aggregate functions.

This support is experimental and is being provided to gather feedback from early adopters. The SPARQL 1.1 syntax can be requested on a query by supplying the "syntax" query argument with the value "SPARQL_11". For example: /jazz/query?syntax=SPARQL_11&q=SELECT+*+WHERE+{+?s+?p+?o+.+}

The following query illustrates the count aggregate function provided by SPARQL 1.1 and counts the number of properties per tasks.

PREFIX task: <http://tasks.org/tasks/>
SELECT ?uri ( count ( ?o ) as ?c )
WHERE {
?uri ?p ?o .
?uri task:status ?status . 
} GROUP BY ?uri 

More information on these SPARQL features can be found on the SPARQL 1.1 site. More information on the query service can be found on the JFSIndexStoreQueryAPI wiki page.

Storage area resources may be defined in RDF/XML, NTriple, or Turtle

Storage area resources are RDF resources. Previously, only RDF/XML was supported for defining a storage area. It is now possible to use the NTriple and Turtle formats to define a storage area. For more information, please see JFSStorageAPI for details on creating storage areas.

New repotools command to compact the JFS index

Jazz Foundation Services use the Jena TDB database to store and query over RDF data. Certain special circumstances can induce the TDB indices to grow very large (Defect 106920). A new repotools command has been provided to alleviate the problem by forcing a compaction of the indices.

This command requires that the server be shutdown beforehand. The syntax of the command is as follows:

{server-install-dir}/repotools.bat -compacttdb
          srcdir={location of TDB indices} [tempdir={location of a temporary directory}]

New repotools command to permanently delete all resources associated with a project area

While it is possible to delete a resource in the JFS Storage Service today, a delete results in the archiving of the resource. When a resource is archived all revisions of that resource continue to be accessible and a part of the history for the URL of the resource. More information on how delete behaves can be found in JFSStorageAPI.

A new repotools command has been provided to enable the permanent deletion of all resources and their history, including revisions, for a project area (see Enhancement 111534 for more details).

The command requires that the server be shutdown beforehand. The syntax of the command is as follows:

{server-install-dir}/repotools.bat -deleteProjectAreaResources
         contextURL={url-of-the-project-area} [force=true|false] [noPrompt]

By default, only archived resources are deleted for the specified project area. If the force parameter is specified with the value "true" then all resources associated to the project area, including resources that haven't been archived, will be permanently deleted. The command will prompt the administrative user to confirm the delete unless the noPrompt parameter is used.

This command does not automatically trigger a reindex. Performing a reindex is recommended if the force parameter is specified. Reindexing can be requested by the repotools.bat -reindex command (also requires the server be shutdown beforehand).

Updates to the Changes API

A significant modification has been made to the Changes support in JFS. The pattern of specifying a storage-in-change-url has changed to emphasize the original resource URL. The pattern had been {change-url}?resource={resource-url}. The pattern is now {resource=url}?change={change-url}. More information about the changes support in JFS can be found in the JFS2StorageChangeAPI wiki topic.

Allow any JFS service be specified in a bulk HTTP request

The bulk HTTP operations had been limited to only the JFS storage service. This limitation has been lifted. More details can be found in Enhancement 111600. More information on the bulk HTTP services can be found in the JFSBulkOperations wiki topic.

A notable result new of this new capability is that bulk changes within a change set can be contributed to the server via a single request. More details on the JFS support for change sets can be found in the JFS2StorageChangeAPI wiki topic. An example of combining the use of the bulk HTTP services and the changes service can be found in the JFSBulkOperations wiki topic.

Text indexing for older MS Formats

Support has been added for text indexing of common Microsoft file formats prior to 2007. More information can be found in Enhancement 110271. The supported media-types for this capability are:

  • application/msword
  • application/msexcel
  • application/mspowerpoint

Query over multiple baselines

Query over baselines was previously limited to a single baseline. Query over multiple baselines is now supported by specifying a comma-delimited list of baselines in the baseline query parameter. More information can be found in Enhancement 100728 and the JFSIndexStoreQueryAPI wiki topic.

License now required for JFS operations

Applications using JFS resource modifying operations (like storage) will now require specific permissions in their client access license (CAL). In order to do so, they need to add new operations to the rules section of their policy.xml files. The JFS operations are associated with the key: "com.ibm.team.jfs.write", meaning that the following addition in rules section would be needed: <operationPattern idPattern="com.ibm.team.jfs.*" allow="true" />

Text indexing for XML literals in RDF

The JFS text indexer is now able to extract plain text from XML literals in RDF content, so they can be searched for using Lucene. Here is an example of a resource with such a XML literal in RDF/XML:

<rdf:RDF xmlns:rm="http://www.ibm.com/xmlns/rdm/rdf/"
         xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
  <rm:Artifact rdf:about="">
    <rm:hasAttrVal rdf:parseType="Resource">
      <rdf:value rdf:parseType="Literal">
        <div xmlns="http://www.w3.org/1999/xhtml">
          <h1 id="_1275509371110">Brief Description</h1>
        </div>      
      </rdf:value>
    </rm:hasAttrVal>
  </rm:Artifact>
</rdf:RDF>

With this new support, a search for "Brief Description" will find matches in this resource, but a search for "h1" or "div" will not.

Last-Modified header in query or search response

The server now includes a Last-Modified response header with each query or search. It corresponds not to the date/time for the query itself but the contents of the timestamp of the last indexed resource. This allows a client to note that the query contains correct values as of the specified date/time. A client MAY then perform a HEAD with the query string and while no query will be performed the returned Last-Modified header would be included and allow the client to determine whether to refresh the query results with a full GET.

In addition to the seconds precision timestamp of the Last-Modified header, the server also provides a milliseconds precision timestamp associated with the X-If-Modified-Since-XSD response header.

More information on how to use query/search conditional headers can be found on the JFSIndexStoreQueryAPI wiki page.

User URL as a security context URL

JFS storage and query/search services now accept user URLs to be used as security context for resources. Prior to this, only project area URLs were eligible.

Here is an example of a user URL passed as a header on a storage POST request:

> POST /jazz/storage/Pocket HTTP/1.1
> Host: lotr.net
> Date: 12-08-2010T18:42:00
> Name: Ring
> X-Jazz-Owning-Context: /jazz/users/Bilbo

One ring to rule them all.

For more information about security contexts, please consult the JFSSecurityContexts wiki page.

API modification on change service commit failure

In case of a conflict when a change is being committed, the server now returns error code 409 with no details in the response body, as this is prevented by most application servers. One should instead request the status for an in-flight change to retrieve the reason(s) of the conflict by doing a GET /jazz/changes/<changeId>?status.

More information on this API change can be found in the 121327:API modification on change service commit failure adoption item, or in the storage change API.

Jazz Foundation Application SDK

SDK name change

The Java SDK for developing Jazz-based applications is now known as the Application SDK; formerly it was called the Server SDK. The name of the download file for the SDK is now of the form "jfs-application-sdk-<version>.zip". The download file now contains both the OSGi and plain Java versions of the SDK libraries.

Application SDK documentation

Application SDK Documentation is available at: https://jazz.net/wiki/bin/view/Main/AppSDK

Libraries

  • com.ibm.team.jfs.app.query -  This library has been optimized to generate queries where all equality tests against literal values are moved to the front of each sub-query graph, resulting in faster executing queries.
  • com.ibm.team.http - The HttpClientService now provides support for inter-app request dispatching, disabled by default. When enabled, this optimization in the HttpClientService detects when a request is bound for the same authority as the source of the request, and uses the JEE javax.servlet request dispatching mechanism to synchronously deliver the request to the target web application, thus avoiding the overhead of a network call. No modifications are needed in the target servlet, nor in the caller of the HttpClientService.
  • com.hp.hpl.jena.rdf - This is a new library for working with RDF. This library replaces (See the required adoptions) the com.ibm.team.jfs.app.rdf library that was earlier part of the Server SDK. The new library is a feature rich/complete alternative to the earlier library.

Application provisioning

Applications deployed using the Jazz Provisioning are now automatically provisioned when the user visits the URL of the application. For example, visiting an application with context root "/myapp" will provision the application on the first request. Earlier an additional install step was required before the application could be used. This new enhancement simplifies the overall deployment experience.

Samples

Samples have been updated to demonstrate following new capabilities of Jazz Foundation:

  • com.ibm.team.jfs.sdk.samples.caching - This new sample demonstrates derived resource caching using the Application SDK caching libraries. In this sample, a service generates and serves metadata for resources retrieved via HTTP. Since generating the metadata from HTTP responses is expensive, the service caches the derived data for subsequent requests. This sample demonstrates a layered approach to specialized caching that uses both local and distributed (memcached) caching
  • com.ibm.team.jfs.sdk.samples.hellojfs - This existing sample has been enhanced to demonstrate usage of Jazz Foundation Storage and Query

JFS Explorer

A new sample, JFS Explorer, has been added to the Application SDK. The JFS Explorer can be used to explore the content of JFS storage and execute any SPARQL query. With the explorer, you can see all storage areas, all resources in a specified storage area, run full text searches, create, edit and delete a resource, and view request and response headers for operations.

You can refer to JFS Explorer as another sample to learn how to create an application using the Jazz Foundation Application SDK and Jazz Foundation Services. It's also pretty handy for debugging.

JFS Explorer

Stepped up to Apache HTTP Components 4.0

Apache HttpComponents Core (org.apache.http) and Apache HttpComponents Client (org.apache.http.client) have moved up to version 4.0.1. This has required us to also update the bundle org.apache.james.mime4j from version 0.4 to 0.6. See work item 90323 for more details.

Added ROME

We've included version 1.0 of the ROME library for parsing and generating feeds. It's in the bundle com.sun.syndication. See work item 95613 for more details.

Application configuration

The JFS SDK application configuration properties have been refactored to use the com.ibm.team.jfs.app namespace. These properties are intended for application bootstrapping, including the discovery of application property files and other runtime dependencies.

  • com.ibm.team.jfs.app.conf: Specifies the root, common application configuration directory (e.g. /conf). If this is the only property set, this directory is assumed to contain context-specific subdirectories named after the application context (e.g. /conf/myapp1).
  • com.ibm.team.jfs.app.context.conf: Explicitly specifies the context-specific configuration directory (e.g. /conf/myapp1).
  • If neither of these properties are set, the SDK will use the JAZZ_HOME java property as the value of com.ibm.team.jfs.app.conf. In this scenario, both the /jazz context and SDK-based app contexts would share the same root configuration directory without additional configuration (default is /jazz/server/conf).

See the adoption work item 94131 for more details. Note that the properties which were deprecated in the 1.0.0.1 release have been removed for the 3.0 release.

OAuthHelper API changes

The com.ibm.team.jfs.app.oauth.OAuthHelper class has been simplified; several overloaded methods have been deprecated. See the adoption work item 101622 for more details.

API changes

Several areas of the SDK API are undergoing revision; there are several new APIs that are not yet fully committed or documented. These new APIs have been marked with "@since" tags that indicate their status. See the Application SDK Usage Guidelines for an explanation of the tagging scheme.

Here are a few notable additions:

  • com.ibm.team.jfs.app.http.client: Apache's HttpClient interface is now the primary client interface for the SDK. IHttpClientService and HttpClientService are deprecated. The JazzHttpClient class is an AbstractHttpClient wrapper that enables HTTP caching and servlet request dispatching for HttpClient implementations. Some of the HttpClient extensions provided by the SDK are still provisional, so early adopters should subscribe to JFS SDK 3.0: com.ibm.team.jfs.app.http.client (105458) for updates.
  • com.ibm.team.jfs.app.resource: Contains utility classes for parsing request bodies and generating response bodies in the RDF/XML and RDF/JSON formats.
  • com.ibm.team.jfs.app.query: Now allows returned properties to be specified hierarchically, so that properties of nested resources can be returned. See work item 105977 for the details.
  • com.ibm.team.jfs.app.query.results: Provides utilities for iterating over the results of a query from the Jazz index query service or the Jazz full-text query service. It uses the StAX parsing library for high-performance parsing of the result stream without buffering it all into memory. See work item 107016 for more information.
  • com.ibm.team.jfs.app.util: The ErrorUtils class can be used to handle errors from Jazz Foundation service requests, generating error reports for clients. The AppLogger class can be used to log HTTP request and response messages.
  • com.ibm.team.jfs.app.http.multipart: Provides helper Java API for working with bulk operation support provided by Jazz Foundation Services. See Jazz Foundation 3.0 Bulk Operations Support. Specifically the API allows clients to build an entity that may contain multiple org.apache.http.HttpRequest objects. It also provides a parser for parsing the multipart response from JFS. The parser parses the response and returns each each part in the multipart response as an org.apache.http.HttpResponse object. For usage instructions see the Application SDK Javadoc.
  • com.ibm.team.jfs.app.discovery.ServiceContributionResourceUtility and com.ibm.team.jfs.app.servlet.util.BaseServiceContributionResourceService can be used by an application to generate the contents of a "service contribution resource" document for use by the new Jazz discovery service. See the documentation for those classes, and Foundation Discovery Services for more information.
  • Three methods have been added to com.ibm.team.jfs.app.oauth.OAuthHelper to aid fronting applications in retrieving OAuth token and principal information from incoming requests: "hasAuthorizationHeader", "getAccessTokenFromAuthorizationHeader", "getPrincipalFromRequest". These methods allow the fronting application to appear as if it is a OAuth provider for the Jazz Team Server that it is associated with.
  • com.ibm.team.jfs.app.http.util.MediaRange has been enhanced to allow an application to perform media type content negotiation using the Apache negotiation algorithm

Discussions building block incubator

The Discussions Building Block is a set of services and a Web UI for adding comments to any resource that can be stored in the Jazz Foundation storage system. The building block is deployed in a separate application that will eventually host several such building blocks.

More information on this application is available on the jazz.net wiki here, as is the preliminary discussion service specification.

Discovery Service helper API

The Jazz Team Server provides a new facility for registering applications and discovering the services offered by those applications and the Jazz Team Server itself. The com.ibm.team.jfs.app.discovery package in the Application SDK provides utilities for querying the discovery service for specific types of services. The Javadoc describes how to use the classes and interfaces in the package, and the HelloJfs sample application has been modified to illustrate how to use the API to determine the URLs for the services it needs.

See Foundation Discovery Services for more information on the new discovery service.

Enhanced error handling utilities

Several classes have been enhanced to simplify the handling of errors in Jazz fronting applications, and to support the Jazz Foundation error reporting format.

  • The com.ibm.team.jfs.app.servlet.AppContainerServlet class now catches all exceptions thrown by REST service methods, and generates an error response from them in the Jazz Foundation error reporting format. Therefore, application REST services need not implement any specific error handling, if this default behavior is suitable for them.
  • The com.ibm.team.jfs.app.error library has been enhanced to allow generating error reports in a JSON format, and to parse an HTTP response into an error report object.
  • The com.ibm.team.jfs.app.util.ErrorUtils class allows an application to define a mapping between HTTP status codes received from a downstream server (e.g. the Jazz Team Server) and the error which will be returned to its client. The incoming request's Accept headers, if present, are used to determine the format of a generated error response, defaulting to RDF/XML.
  • If an error report is generated from an instance of the com.ibm.team.jfs.app.http.JfsHttpException class, it will include the new string-valued "sub-status" attribute that was added to that class (replacing the previous integer-valued attribute, which has been deprecated).

See story item 111595 for more details on the error handling enhancements.

Plain Java library consolidation

The number of JAR files for the plain Java version of the SDK has been reduced significantly, from 43 to 25, by combining all of the Jazz Foundation libraries into a single JAR file. The other JAR files are for third party libraries that are required by the SDK libraries.

Tasks sample

The Tasks sample has been completely re-written to demonstrate the current programming model. The new version demonstrates the usage of new APIs in the SDK; e.g. Content-Negotiation, JazzHttpClient, RdfJsonEntity. The result of this re-write is a much smaller and easier to understand sample. The UI for the sample has also been re-written to match the look and feel of the Jazz-based UIs.