Copyright (c) 2003 The dbXML Group, L.L.C. All rights reserved. See doc/LICENSE for The Labrador License Table of Contents ================= Introduction Target Platforms Release Notes Acknowledgments Introduction ------------ Labrador is an open source modular Web Services Hub. Labrador is designed to be incredibly simple to use for developers who are programming Web Services. Typically, only one line of code is needed to make your Object instance available. Labrador is also designed to be easy to extend for those developers who need the hub to provide additional functionality. For example, Labrador also supports the ability to execute stored procedures and other SQL statements using any of the protocols that Labrador exposes. Labrador is meant to allow objects to be exposed as Web Services using a variety of protocols, such as SOAP, REST and XML-RPC. It does not attempt to provide full-featured toolkit-style implementations of the protocols that it supports, and doesn't provide any client functionality. Its focus is to be a simple, and easily configured Web Services Hub that allows multiple protocol handlers, instance resolvers, and service models. Target Platforms ---------------- The Labrador code base is written in Java, and requires JDK 1.4 or higher to operate. The following is a list of tested platforms and the JDK version that was used: Platform Java VM Used =========== ======================== Mac OS X Apple's Java 2 SDK 1.4.1 Solaris Sun's Java 2 SDK 1.4.1 Linux Sun's Java 2 SDK 1.4.1 Release Notes ------------- Version 0.7 =========== The Labrador project has been revived after a long hiatus. This version is now being maintained officially by The dbXML Group, and also includes a new Apache style license. The changes are too numerous to mention, but what follows is a list of the more notable modifications. - New package name is com.dbxml.labrador - Labrador's Variant class and parameter marshalling system now support JAXB-generated class conversion. - Labrador's HTTP server has now been broken into two separate server implementations. One implementation is a standard HTTP server whose default port is 7280. The standard server utilizes Java 1.4's multiplexed I/O in order to provide improved performance. The other implementation is a secure HTTP server whose default port is 7643. Because the secure HTTP server uses Sun's SSL extensions, it cannot yet be implemented using multiplexed I/O. - A very simple, but configurable logging Filter has been added. This Filter does not currently perform archiving, but may in a future release. Also, because Filters are currently only invoked before the instance is called, the logging Filter can't capture error conditions. This may change in a future release as Filters *may* introduce exit filtering. - A session management Filter has been added. This filter allows sessions to be managed contextually so that session objects are scoped to a specific context. All instances below that context can share those session objects. Any instances outside of that context are restricted from accessing those objects. Also, the derived Session class that is used can be configured per context so that a developer can intercept Session lifecycle events. By default, Labrador defines a single context ("/"), so all objects are shared by all instances. - Most of the Broker methods now throw Exceptions instead of returning null. Though this will not require any changes to client code, it may require fixing code that extends Labrador itself such as custom Resolvers. - A new class called ID is used in place of Strings in order to identify objects. The ID class will automatically canonicalize paths internally, so the following evaluation will return true. new ID("test").equals(new ID("/test")) Creating a new ID with the default constructor will create a unique ID in the form: /oid/0123456789ABCDEF0123456789ABCDEF. This unique ID takes into consideration the host's IP address, current time, and a separate sequence, so it can be assumed to be somewhat globally unique. Because ID replaces String, some of the method signatures of the ObjectResolver and SimpleObject classes have changed. Methods that took String parameters as names now take ID parameters as identifiers. - The Handler interface now exposes a method called processError. processError will be called by Labrador if a processing error occurs after the Handler has already been resolved. In this case, the error will be exposed as a protocol-specific error, which will avoid the vague HTTP 500 server errors that had been presented in the past. - The REST handler now supports arrays and POSTed data. When processing the parameters for a method call, if the REST handler sees that a parameter is not provided, but finds that there is POSTed data, it will attempt to resolve that data to the missing parameter. This works well for document and byte array postings. - The JDBCResolver is now minimally functional, but needs extensive testing. See doc/index.html for a quick example of how to map SQL statements to JDBCInstances. Version 0.6 =========== Fixed several bugs, including Null Pointer and I/O bugs. - Added a bootstrapping system. By default, Labrador will bootstrap using a configuration file that is located in the org/notdotnet/labrador directory of the labrador.jar file. You can specify a system property to override the default configuration file. To do this, set the VM's system property called labrador.config to the new configuration file location (ex: -Dlabrador.config=/home/tom/labrador.xml). You can either use an absolute file location or a URI. - Added a shell script called 'labrador' in the bin directory that allows you to start up the Labrador HTTP Server with a set of command-line specified static service instances. - All bootstrapped components can be configured via the Labrador XML configuration file. Static instances can implement a static method called setConfig(Configuration) and constructed instances can implement the Configurable interface. The Configuration instance that is passed to the component is the entire configuration block for the component. - Added an interface called BrokerContext. A thread-local instance of this interface can be retrieved from the Broker. BrokerContext contains all of the components (Filters, Resolvers, Handlers, etc) that have been used to process the service request. - Filters can now be implemented to filter the processing chain before actual service invokation. These filters can be used to set BrokerContext properties for things such as authentication and state management. - Added some additional management functions to the Broker to allow the listing and removal of Handlers, Resolvers, Filters, and Describers. - Renamed the Registry to InterfaceService to clarify its purpose. Also started developing a basic NamingService. Version 0.5 =========== Several major bugs have been fixed, including a major oversight in the XML-RPC implementation having to do with structure marshalling. A basic Registry has been implemented. A Describer based on a simple description language called SWSS has been implemented. Still no SOAP implementation, but it is in the works. - Fixed a bug that was causing NullPointerExceptions when marshalling XML-RPC structures. - Fixed several bugs related to type and array type conversions. - Added a basic Registry. The Registry can be accessed like any other Instance using the id "org/notdotnet/services/Registry". - Currently, only one description format is available. It is a simple description language called SWSS, and is described in the file doc/SWSS. WSDL will be added as the SOAP implementation is built out. - Added an Registry access example in RegistryClient.java. - Simplified several of the interfaces a bit. Version 0.4 =========== The most immediate thing you'll notice about this release is that Project Labrador now exists in the org.notdotnet.labrador package. NotDotNet is going to be a larger effort to produce a simple, open source web services technology based on Java, and not affiliated with any major corporation (like Sun or Microsoft). JavaDoc and other documentation have also been filled out a little more. - New Java package used is org.notdotnet.labrador. - The standard package has been renamed to objects. - License attributions have changed (see doc/LICENSE). - Added an architecture diagram that explains some of the basic components of the Labrador framework. - Began adding examples of Labrador servers and XML-RPC clients for invoking those servers. Version 0.3 =========== This version introduces several improvements in the type system and the APIs. Also, several bugs have been fixed, and the API has been documented quite a bit more using JavaDoc. - XML-RPC DateTime values are now supported as well as Base-64 values. Base-64 values are converted to and from byte arrays by the XML-RPC Handler. The Variant class also now supports Dates. - The Discovery interface is now being passed into the Handler by the Broker. Also, Discovery now includes method parameter names if the Resolver supports such introspection. - A Describer interface has been added to serialize Discovery meta-data into a client-consumable format (ex: WSDL). - Array and Type conversions have been moved into their own utility class, and have been built out quite a bit for future use. Also, type conversions have been improved in the XML-RPC Handler for both array and non-array object types. Version 0.2 =========== This version introduces better type conversions, better array support, lots of bug fixes, and an internal HTTP Server. Still no SOAP support, but it should be ready by version 0.5. Also, still no DateTime support, which you can expect in 0.3. Version 0.1 =========== Labrador is being spun off from the dbXML Core project. It is based partially on the XMLObject subsystem as well as the GetObject (SOAP) module that dbXML provided. These subsystems were valuable enough, and generic enough to evolve beyond dbXML itself, and so have been established as a stand-alone project. Basic XML-RPC functionality is available, but there is practically no working SOAP code. All native data types are supported as well as String, List, Map, Document, DocumentFragment, Element, and Variants. Date/time functionality still needs to be filled out as well as better conversion between Variant types. Arrays are also supported for most types. Acknowledgments --------------- This product includes software developed by the Apache Software Foundation (http://www.apache.org/)