NEWS

** NEWS file is deprecated. Future updates will be documented directly in CHANGES **

Airlift 0.139

Minor maintenance release. See CHANGES.

Airlift 0.138

Minor maintenance release. See CHANGES.

Airlift 0.137

Minor maintenance release. See CHANGES.

Airlift 0.136

Minor maintenance release. See CHANGES.

Airlift 0.135

* Units

The units module has been extracted into a separate, standalone
project. The Maven groupId and artifactId are the same, with the
version updated to 1.0.

* Upgrade to Jackson 2.8.1

Airlift 0.134

Minor maintenance release. See CHANGES.

Airlift 0.133

Minor maintenance release. See CHANGES.

Airlift 0.132

Minor maintenance release. See CHANGES.

Airlift 0.131

Minor maintenance release. See CHANGES.

Airlift 0.130

Minor maintenance release. See CHANGES.

Airlift 0.129

Minor maintenance release. See CHANGES.

Airlift 0.128

Minor maintenance release. See CHANGES.

Airlift 0.127

* HTTP/2 support

The HTTP server and client now have experimental support for the HTTP/2
protocol for HTTP only (not HTTPS). The server supports the HTTP/2
cleartext upgrade mechanism (h2c) which allows running both versions
of the protocol on the same port. Both versions are always enabled.

The HTTP client also supports HTTP/2 cleartext. However, there is
no upgrade mechanism, so if HTTP/2 is enabled, the client will always
use the HTTP/2 protocol and thus can only communicate with HTTP/2
servers. Attempting to connect to an older server will result in
"refused_stream_error". Thus, HTTP/2 is disabled by default.

* HTTP Client API changes for Case-Insensitive Headers

HTTP header field names are always lowercase in HTTP/2. They should
always be treated as case insensitive, but the previous HTTP client
API made that difficult by returning a map of strings.

The Response interface and various ResponseHandler response objects
now use the new case-insensitive HeaderName class. Additionally,
these objects now have a getHeaders() method that takes a field name
and returns a list of field values.

Airlift 0.126

Minor maintenance release. See CHANGES.

Airlift 0.125

Minor maintenance release. See CHANGES.

Airlift 0.124

Upgrade jmxutils which fixes the server not starting when LogJmxModule
is used due to a Java 8 compatibility issue with jmxutils.

Airlift 0.123

TestingHttpClient now uses a custom Processor interface that allows throwing
checked exceptions instead of Guava Function. This change is is generally
source-compatible but not binary-compatible.

AsyncSemaphore now use JDK Function instead of Guava Function. As above,
this change is generally source-compatible but not binary-compatible.

Airlift 0.122

Minor fixes to Jackson serialization.

Airlift 0.121

Minor maintenance release. See CHANGES.

Airlift 0.120

Minor maintenance release. See CHANGES.

Airlift 0.119

Minor maintenance release. See CHANGES.

Airlift 0.118

Minor maintenance release. See CHANGES.

Airlift 0.117

Minor maintenance release. See CHANGES.

Airlift 0.116

* Default Config Fixes

Configuration defaults bound with an annotation were not being applied due to
a bug.  This also caused HTTP client defaults to not be applied.

* HTTP Selector and Acceptor Pool Configuration

In installations with a high HTTP request volume the default selector and
acceptor pool sizes in Jetty are too small which causes requests to backup
in OS queues and eventually fail.

Airlift 0.115

Minor changes to logging configuration. See CHANGES.

Airlift 0.114

Minor changes to logging configuration. See CHANGES.

Airlift 0.113

Minor maintenance release. See CHANGES.

Airlift 0.112

Minor maintenance release. See CHANGES.

Airlift 0.111

* SPNEGO

This version adds experimental support for SPNEGO auth for Http client.
The following options can be used to set up global Kerberos configuration:

    http.authentication.krb5.config
    http.authentication.krb5.credential-cache
    http.authentication.krb5.keytab

SPNEGO needs to be configured on a per-client basis with the following options:

    http-client.authentication.enabled
    http-client.authentication.krb5.remote-service-name
    http-client.authentication.krb5.principal


Airlift 0.110

* Future Utilities

We've added MoreFutures class which contains utility methods for Future and
the new Java8 CompletableFuture.  For basic future, there are methods for
fetching the future value with minimal exception handling.  For
CompletableFuture, there are methods for easily creating futures.  Finally,
we have added methods for converting to and from Guava ListenableFuture to
ease the transition to CompletableFuture (note, these methods will be removed
in a future release)

Airlift 0.109

* Default Config

An application typically needs to override the default configuration of some
components. For example, the default timeouts in the HTTP client are too large
for communication between workers in a data center.  Rather than requiring
these applications to ship with a default configuration file, we added the
ability to change the defaults for any configuration object.  The following
example changes the default store time-to-live to 1 minute in the sample
server:

    configBinder(binder).bindConfigDefaults(StoreConfig.class, storeConfig -> {
        storeConfig.setTtl(new Duration(1, MINUTES));
    });

Additionally, we have added support for overriding HTTP client defaults during
binding.  For example, this code changes the default idle timeout to 2 seconds:

    httpClientBinder(binder).bindHttpClient("event", ForEventClient.class)
            .withConfigDefaults(config -> {
                config.setIdleTimeout(new Duration(2, SECONDS));
            });

Airlift 0.108

Minor maintenance release. See CHANGES.

Airlift 0.107

We have replaced use of SLF4J in the logging backend with a custom logging
implementation directly connected to Java util logging.  This eases management
of logging dependencies as the core codebase no longer depends directly on any
third party logging frameworks.

Airlift 0.106

Minor maintenance release. See CHANGES.

Airlift 0.105

Minor maintenance release. See CHANGES.

Airlift 0.104

Minor maintenance release. See CHANGES.

Airlift 0.103

Minor maintenance release. See CHANGES.

Airlift 0.102

* Threads

Thread factories provided by the Threads utility class now add threads to a
ThreadGroup.  Some tools organize threads by ThreadGroup which makes it easier
to work with servers with lots of threads.  The ThreadGroup is named using:

    String.format(nameFormat, "group")

This means the nameFormat must expect a String argument instead of an int.  To
ease migration, the code adapts formats with a single %d, but this will be
removed in a future release.

Airlift 0.101

The previous implementation of dense HyperLogLog had an issue where errors
introduced by a loss of information would compound when many instances were
merged together. The new implementation is backward compatible with serialized
HLLs generated by older versions.

HyperLogLog now supports up to 64k buckets.

Airlift 0.100

The previous implementation of sparse HyperLogLog had an issue where errors
introduced by a loss of information would compound when many instances were
merged together. We've replaced it with a new implementation that doesn't
suffer from this problem, but the change in the serialization format breaks
backward compatibility.

Airlift 0.99

* Java 8 is now required

Moving forward, Airlift will be written using the new Java 8 syntax and APIs, and
releases will be compiled using Java 8. This means Java 8 is required for
running Airlift-based servers or using using Airlift libraries.

Airlift 0.98

Minor maintenance release. See CHANGES.

Airlift 0.97

* AsyncSemaphore

AsyncSemaphore is a non-blocking concurrency throttler for asynchronous tasks.
It guarantees that no more than a fixed number of asynchronous tasks will be
outstanding at any point in time without blocking any submission threads. Task
completion is determined by a ListenableFuture returned by the supplied submitter
function.

Airlift 0.96

* AbstractConfigurationAwareModule

Extending this module makes it easy to access configuration at binding time,
which allows conditionally installing modules or bindings based on config.

* Upgrade to Guava 18.0

* HttpClient

We have removed the deprecated interface AsyncHttpClient and binder method
bindAsyncHttpClient(). These can be replaced with HttpClient and
bindHttpClient(), respectively.

* HttpServer

The HTTP server now shows stack traces in error responses by default. To
disable this behavior, set "http-server.show-stack-trace" to "false".


Airlift 0.95

* Discovery

We have added Announcer.forceAnnounce() and ServiceSelector.refresh() which
make synchronizing announcing with a discovery server easier.  This is
particularly useful for testing.

Airlift 0.94

* SetThreadName

The SetThreadName class takes advantage of try-with-resources to safely rename a
thread and restore its original name when it goes out of scope.

Here's a usage example:

    try (SetThreadName ignored = new SetThreadName("query-%s", queryId)) {
        ...
    }

* HttpClient

JettyHttpClient would request GZIP responses if constructed manually using a
rarely used second constructor.


Airlift 0.93

* Thread Factory

We have changed the thread factory implementations to capture the thread context
class loader during factory creation and set this class loader on threads created
by the factory.

* Smile mapper

We have added a JAX-RS mapper encoding responses using Smile.  Smile is a highly
efficient binary encoding of JSON data.  For more information on Smile see:
http://wiki.fasterxml.com/SmileFormatSpec

Airlift 0.92

* JAX-RS 2

We have upgraded to Jersey 2.9.1 which implements the JAX-RS 2 specification.  As
part of this upgrade we have introduced an explicit binder for JAX-RS resources.
For example the following registers the person JAX-RS resource:

   JaxrsBinder.jaxrsBinder(binder).bind(PersonResource.class)

The new explicit binding code is backwards compatible with the "binding scraping"
code, so you do not need to immediately update your code.  The new JaxrsModule
will print a warning for each resource that was not explicitly bound, so it is
easy to find update existing code Once you have updated everything, set the
"requireExplicitBindings" when constructing the JaxrsModule to prevent
regressions.  In a future version we will remove the backwards compatibility,
so please update soon.

Airlift 0.91

Minor maintenance release. See CHANGES.

Airlift 0.90

Minor maintenance release. See CHANGES.

Airlift 0.89

* BoundedExecutor

BoundedExecutor is a light-weight executor decorator that guarantees that no more
than a certain number of threads will run tasks submitted through it. Multiple
BoundedExecutors that delegate to the same underlying executor will a fair share
of the threads proportional to the configured limit.


Airlift 0.88

* HttpClient

This release fixes a couple of performance issues and bugs in the HttpClient:
  - The client was inadvertently requesting GZIP responses. We've disabled this
    behavior since it affects CPU utilization.
  - We've fixed an issue in the way the response buffers are managed that
    affects performance due to unnecessary resizing.
  - The maximum response size was hard-coded instead of using the existing
    config option.

* HyperLogLog

We've added an implementation of HyperLogLog for cardinality estimation.


Airlift 0.87

* HttpUriBuilder

We've added support for constructing Http URIs with IPv6 addresses in the
host part.

    URI uri = HttpUriBuilder.uriBuilder()
                .scheme("http")
                .host("FEDC:BA98:7654:3210:FEDC:BA98:7654:3210")
                .port(8081)
                .build();

    assertEquals(uri.toASCIIString(), "http://[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:8081");

* Jetty updated to 9.1.3

Airlift 0.86

* Upgrade to Jetty 9.1

We have upgraded the Jetty server to version 9.1.2 which includes support for
the Servlet API 3.1, websockets and SPDY with server side push.  In Jetty 9,
the team rewrote significant portions of the core engine which results in a
dramatic reduction in latency.

* Replaced NettyHttpClient and ApacheHttpClient with JettyHttpClient

We replaced the custom HttpClient based on Netty with the far superior Jetty
http client.  The new JettyHttpClient handles both synchronous and asynchronous
requests using a single client, so you no longer need to bind multiple clients.

To migrate to this version you will need to make the the following changes:

  - Replace direct uses of ApacheHttpClient, StandaloneNettyAsyncHttpClient
    and NettyAsyncHttpClient with JettyHttpClient

  - The AsyncHttpClient interface is now deprecated and can be replaced with
    HttpClient which now has asynchronous methods.

Airlift 0.85

* JsonCodec

The JsonCodec.jsonCodec() factory method now uses Guava's TypeToken rather than
Guice's TypeLiteral. This backwards incompatible change allows using the json
module without a dependency on Guice.


Airlift 0.84

* NOTICE file

We made a minor improvement to allow projects that generate binary tarballs using
airlift packaging to include a NOTICE file. To take advantage of this feature,
place the NOTICE file at the root of the maven module.

Airlift 0.83

* Upgrade to Guava 15.0


Airlift 0.82

* Fix bug where the launcher was not starting processes in the data directory


Airlift 0.81

* Return local announcements from service selectors

Local announcements will always be included in the list of services
returned from a service selector. For services that need to see their
own announcements, this improves reliability by removing a race condition
and allows them to run without a discovery server for testing purposes.


Airlift 0.80

* Launcher

This release fixes an important issue in the new Python-based launcher introduced in 0.79
that prevents servers from starting properly. If you're relying on packaging/launcher, you
should upgrade to this version.


Airlift 0.79

* JMX agent

We've replaced the custom JMX agent in airlift by the one built into the JVM.
This change makes it possible to use the VisualGC plugin for VisualVM when jstatd
is also running in the same machine as the airlift-based process.

As a result of this change, we've also removed the 'jmx.rmiserver.hostname' configuration
option in favor of Java's native configuration option 'java.rmi.server.hostname'.

* TimeStat

We've deprecated TimedStat in favor of TimeStat. The new implementation operates with nanosecond
granularity instead of milliseconds, provides more accurate results for quantile queries
and supports Java 7's try-with-resources syntax:

    TimeStat stat = ...
    try (BlockTimer ignored = stat.time()) {
        // do something
    }

* Roll http request log

The http-request.log created by the http server module is now rolled and compressed
on a daily basis.  This change makes the http request log work the same way as the
server.log file.  The default retention for log files is:

    http-server.log.retention-time = 15d


* Launcher

We've reimplemented the launcher in Python. It is compatible with Python 2.4, which is
generally available in most Unix distributions. This means there's no longer a dependency
on Ruby 1.9.

As part of the rewrite, we've fixed some long-standing issues and added a couple of features:
- Application logs are now written to var/log/server.log instead of launcher.log.
- stdout/stderr from the JVM is now redirected to var/log/launcher.log. This is necessary
  for capturing thread dumps and other VM diagnostics output.
- If the package contains a 'plugin' directory, it will be symlinked into the data directory.
  This makes it possible for the server to locate and load plugins dynamically when the
  data directory does not match the installation directory.
- All jar files in the lib directory are now used to build the classpath for the process. This
  makes it easier to re-package servers and add new dependencies (e.g., database drivers),
  without having to rebuild the server jar file and the manifest classspath.
- In 64-bit Linux, tools like ps, top, etc will now show a custom name for the Java process
  (instead of just 'java'). The name can be overridden by setting the "process-name" property
  in the server pom file. The default value is determined by the artifactId of the pom.
- pid file handling is now more robust and no longer suffers from issues due to stale pid files

Important: projects that depend on Airbase need to upgrade to version 8 or higher.


Airlift 0.78

* Units

We've made a backwards incompatible change to the Duration API to align with
the DataSize API.  The new Duration code has many new features:

- Duration remembers the original unit, so parse and print round trips
- toMillis() returns a long so it is easier to use with normal Java APIs
- roundTo(TimeUnit) return a long in the specified unit
- convertToMostSuccinctTimeUnit() will select the TimeUnit to produce
  the easiest to read value
- timeUnitToString(TimeUnit) to get a clean short name for TimeUnits

To update to the new api, you will need to:

  convertTo(TimeUnit) now returns a Duration instead of a double
    - use getValue(TimeUnit) for the old behavior

  toMillis() now returns a long instead of a double
    - use getValue(MILLISECONDS) for the old behavior

  toString() returns a string in the original units instead of millis
    - use toString(MILLISECONDS) for the old behavior

This API remains in BETA, and is subject to additional backwards incompatible
changes.


* HttpClient exception handling

We have redesigned exception handling in the HttpClient.  In the new design,
the handle or handleException method of the Response handler should be called
once per execution.  To make this change we had to make some backwards
incompatible changes.

The new signature for handleException in the ResponseHandler is:

    T handleException(Request request, Exception exception)
            throws E;

This allows the handler to return a "default" value when an exception occurs,
and makes it much clearer to the user how to implement the method.


The AsyncHttpClient.executeAsync method now returns a ListenableFuture instead
of a CheckedFuture.  Any caller that was using the checkedGet() method of
CheckedFuture will need to change to get() and handle the exceptions or use
one of the helper methods in Guava Futures.

This API remains in BETA, and is subject to additional backwards incompatible
changes.


* NodeInfo

The IP address detection code now verifies that the address discovered from
the machine's hostname is actually available for use (i.e it is assigned to
the machine and the interface is up). This eliminates the problem of a
machine having a hostname that actually resolves to a different machine.

The TestingNodeModule produces a NodeInfo that is always set to localhost.
This causes unit tests to always bind to localhost rather than the public IP
of the machine, which is safer and reduces potential problems.


* Discovery ServiceSelectorManager

We added a ServiceSelectorManager to the discovery client that allows fetching
or refreshing all service selectors. This is useful for tests or for forcing a
refresh of selectors at startup after the initial announcements have been made.


Airlift 0.77

* QuantileDigest

We made a number of improvements to QuantileDigest. QuantileDigests now support
negative values, can be serialized/deserialized and merged with other QuantileDigests.

Important: QuantileDigest is no longer thread-safe, so if you have code that relies
on this guarantee, you'll need to update it to provide thread-safety at that layer.

Airlift 0.76

* Rack server support has been moved to a separate project: airlift-rack
* Added TestingHttpClient to simplify testing

Airlift 0.75

* Minor bug fixes

Airlift 0.74

* Experimental modules

The trailing "-experimental" has been removed from all artifact names.
Any APIs that are experimental should be annotated with @Beta instead.

* AsyncHttpClient now uses less threads when using multiple clients.

Airlift 0.73

* AsyncHttpClient fixes

This release contains a number of fixes for the AsyncHttpClient and additional
changes to ease debugging of async requests.  In some cases the ResponseHandler
would not be notified of errors with the handleException method, even though
the future returned from the executeAsync method would be notified of the
error. To help with debugging, the executeAsync method now returns an
AsyncHttpResponseFuture which has a new method getState that can be used to
determine the current state of the http request.  This is helpful when requests
seem to get lost after execution.  Finally, we have changed the Netty setup to
properly name the worker threads, so you can more easily find the http client
threads.

Airlift 0.72

* Multiple Event Implementations

The event system now support multiple back end implementations simultaneously.
Events are simply sent to each back end.  The existing event implementations
have been retrofitted and no code changes are necessary.  The NullEventModule
has been deprecated in favor of the new EventModule, which has no event
contains the base event system with no back end implementation installed.

* Removal of jax-rs classes from clients

We have replaced all uses of jax-rs classes in clients with classes from Guava
or new classes in the Airlift http client.  In particular, the HttpHeaders and
MediaType classes in jax-rs has been replaced with HttpHeaders and MediaType
in Guava, and the Status and CacheControl classes have been replaced with
HttpStatus and CacheControl in the Airlift http-client.  This reduces the size
of clients and avoids some packing problems with the latest jax-rs releases.
Any existing code can continue to use the jax-rs versions of these classes, but
jax-rs is no longer required.

Airlift 0.71

* New build system

Removed the library POM. Uses the airbase project as base pom for building.

* Global dependency upgrades

- Jetty to 8.1.9
- Guava to 14.0
- BVal to 0.5
- slf4j to 1.7.2
- logback to 1.0.9
- Jersey to 1.17.1
- Joda Time to 2.1
- TestNG to 6.8
- Mockito to 1.9.5
- Hamcrest to 1.3

* Specific dependency upgrades

- JMX: jcommander to 1.30
- DBPool: mysql connector to 5.1.23
- DBPool: h2 to 1.3.170
- httpclient: httpclient to 4.2.3
- httpclient: httpcore to 4.2.3

* Dependency changes

com.google.code.findbugs:jsr305 was replaced with com.google.code.findbugs:annotations

The jsr305 jar contains only the JSR 305 annotations while the
annotations jar also contains additional, Findbugs specific
annotations.

* Replacing the library and rest-server-base pom with airbase

Projects using the airlift/library and airlift/rest-server-base poms as their
parent must switch to use airbase (https://github.com/airlift/airbase/).

Replace the parent section with

    <parent>
        <groupId>io.airlift</groupId>
        <artifactId>airbase</artifactId>
        <version>... latest version ...</version>
    </parent>

when replacing the rest-server-base, it must also activate the airlift
packaging by creating a file called `.build-airlift` in the directory
of the module or sub-module that should be packaged as an airlift
packaged project.

As airbase provides packaging independently, the version of airlift
used for packaging and launcher is controlled with
`dep.packaging.version`. To ensure that a project uses the same
version for airbase while building and packaging, factoring out the
version of airlift in the parent pom is recommended:

    <properties>
        <dep.airlift.version>0.71-SNAPSHOT</dep.airlift.version>
        <dep.packaging.version>${dep.airlift.version}</dep.packaging.version>
    </properties>
    ...
    <dependencyManagement>
        <dependencies>
            ...
            <dependency>
                <groupId>com.facebook.airlift</groupId>
                <artifactId>bootstrap</artifactId>
                <version>${dep.airlift.version}</version>
            </dependency>

            <dependency>
                <groupId>com.facebook.airlift</groupId>
                <artifactId>configuration</artifactId>
                <version>${dep.airlift.version}</version>
            </dependency>
            ...
        </dependencies>
    </dependencyManagement>

`dep.airlift.version` is picked up when the project is built and
`dep.packaging.version` is used when the project is packaged.

* Logging

The com.facebook.airlift.log.Logger API was updated to work directly against Java's built-in
logging APIs. This is intended to make it easier to allow code that runs in isolated
classloaders to use the logging system and should have no visible effects.

Airlift 0.70

* Upgrade to Jackson 2.1.x

Jackson 1.x has been upgraded to 2.1.x. This requires substantial code and
dependency changes as all the artifacts are named differently and all the
classes are in different packages. The upgrade guide has more details:
http://wiki.fasterxml.com/JacksonUpgradeFrom19To20.

The Json module now also supports Jackson Modules (more details at
http://wiki.fasterxml.com/JacksonFeatureModules).

* True async http client

The AsyncHttpClient has been rewritten on top of Netty.  As part of this
work, the AsyncHttpClient has been converted into an interface and the
main implementation is NettyAsyncHttpClient. Additionally, the execute
method has been renamed to executeAsync so the AsyncHttpClient can extend
HttpClient.  The change is to simply replace:

    asyncHttpClient.execute(request, responseHandler);

with:

    asyncHttpClient.executeAsync(request, responseHandler)

The other main change is when using the HttpClientBinder.  The bindAsyncHttpClient
method now binds both an AsyncHttpClient and a HttpClient, so if you were binding
both before, you will need to remove the call to bindHttpClient.

This API remains in BETA, and is subject to additional backwards incompatible
changes.

* Socks proxy support in http client

The new NettyAsyncHttpClient supports connecting to servers through a socks proxy.
This is particularly useful for accessing production servers.  The easiest way
to use this feature is to establish a socks proxy using ssh, as follows:

    ssh -N -D 1080 any.server.running.sshd

Then simply set the HttpClientConfig SocksProxy property either directly in code
or via the following config option:

    myclient.http-client.socks-proxy = localhost:1080

* BETA: Bootstrap for testing

The Bootstrap class performs may initialization tasks for servers, but when
testing not all installation tasks are desired.  Specifically, the Bootstrap
class loads configuration properties from a file specified using System
property.  The new setConfigurationProperty and setConfigurationProperties
have been added to supply the properties directly.  Another, problematic
task is logging initialization, which can now be disabled with the new
doNotInitializeLogging() method.  For an example of Bootstrap a test see
com.facebook.airlift.sample.TestServer.


Airlift 0.69

* In this release we have upgraded the following dependencies

  - jmxutils 1.13
  - Jackson 1.9.12


Airlift 0.68

* Support for v1 events has been removed

* HTTP client shutdown

The HttpClient and AsyncHttpClients now implement Closeable and properly
shutdown when used as lifecycle objects. Calling close shuts down the
connection pool for the underlying Apache HTTP client.

* Pretty-printed JSON

The injected JsonCodecFactory and injected codecs no longer produce
pretty-printed JSON. The previous behavior was a bug. JsonCodecFactory
has a method to return a factory that produces pretty-print codecs.


Airlift 0.67

* Cassandra module has been removed

Starting with this version, the Cassandra module is no longer supported

* DataSize and Duration can now be serialized as json

* In this release we have upgraded the following dependencies

  - Apache HttpClient 4.2.2


Airlift 0.66

* Java 7 is now required

Moving forward Airlift will be written using the new Java 7 syntax and APIs, and
releases will be compiled using Java 7.  This means Java 7 is required for
running Airlift-based servers.

* No thread pool for CounterStat

We changed the CounterStat implementation to use forward decay, which eliminates
the need for a thread pool (and having to manage a thread pool).

* HttpUriBuilder a fluent api for HTTP URIs

Building HTTP URIs using java.net.URI is difficult and error prone, so we added
a simple fluent API for building up HTTP URIs.  For example:

    URI uri = uriBuilder()
            .scheme("http")
            .host("www.example.com")
            .port(8081)
            .replacePath("/a/b/c")
            .replaceParameter("k", "1")
            .build();

Additionally, the API can manipulate existing URIs:

    URI uri = HttpUriBuilder.uriBuilderFrom(URI.create("http://www.example.com:8081/?a=apple&b=banana"))
            .replaceParameter("a", "apricot")
            .appendPath("a/b/c")
            .build();

* Bind Jackson key serializers and deserializers in Guice

We've added the ability to bind Jackson key serializers and deserializers with
the JsonBinder.

* Configuration types can now use a fromString method for coercion

The configuration system will look for methods in the following order:

    fromString(String);
    valueOf(String);
    <init>(String);

* Quantile Digest

We've introduced an implementation of Quantile Digests, a data structure for computing approximate
quantile statistics and histograms in sub-linear space with guaranteed error bounds, from the paper
"Medians and Beyond: New Aggregation Techniques for Sensor Networks". It supports
exponentially-decayed counts and can be used to query quantiles and histograms very efficiently.

* DistributionStat

We've deprecated MeterStat in favor of DistributionStat. This new implementation is based on
QuantileDigest and exposes statistically valid percentile metrics at various resolutions
(1/5/15-minute, all time). It's designed to be exported via jmxutil's @Managed annotations.


Airlift 0.65

* Re-packaged the project under io.airlift

Platform 0.64

* Fix bug that prevented skeleton server from starting

* Enforce use of HttpClientBinder

The previous way of using HttpClient was to create a new instance of the
HttpClientModule or AsyncHttpClientModule for each client. The recent addition
of filter support added a binding API, HttpClientBinder. The use of this API
is now required. The modules cannot be used directly anymore. Here is an
example of how to use the binder:

    httpClientBinder(binder).bindHttpClient("foo", FooClient.class)
        .withFilter(FirstFilter.class)
        .withFilter(SecondFilter.class);

Here is a simpler example to create a client for use with other platform
services. The client will pass the trace token when making requests:

    httpClientBinder(binder).bindHttpClient("foo", FooClient.class).withTracing();

Platform 0.63

* Fix bug that prevented sample and skeleton servers from starting

Platform 0.62

* Removed all dependencies to Ning's Asynchronous HTTP client

Since http-client-experimental now replaces the usage of Ning's Asynchronous
HTTP client, we've removed all existing references to that package.  Rest
servers that upgrade to 0.62 may need to include it as an explicit dependency
if they don't want to upgrade.

* Cleaned up dependency management

There is now a library project that contains a single parent dependencyManagement
section for all poms to inherit from.  This now includes REST Server Base.  This
ensures that all platform libraries are built with a single set of versions that
produce fully compatible dependency closures with the services that consume them.

* Multiple refactoring commits for readability

There were multiple refactoring efforts to enhance readability.  Some classes that
moved include:
RequestBuilder -> Request.Builder
EchoServlet is a separate class now
MediaType is now available as a class in Guava 12

* Addition of request filter support to HttpClient

HttpClients may now bind in request filters, an example of such can be found by
following the code in com.proofpoint.http.client.TestHttpClientBinder.  This
was added to support having the TraceToken added into outbound http client requests.

* Removal of deprecated JavaUrlHttpClient

* Removal of the experimental module, segmented into separate modules

At this time, we will no longer have a single experimental module, please be aware
of classes that have the @Beta annotation going forward.  Such classes are subject
to backwards incompatible changes.

Platform 0.61

* Upgrade Platform and Rest Server Base pom to Guava 12.0

* Tests for keep alives with ApacheHttpClient

Platform 0.60

* Fixed bug that prevents Rack servers from announcing

Platform 0.59

* Hibernate validator replaced with direct dependency on Apache BVal

We replaced the indirect use of the Hibernate validator with a direct
dependency on Apache BVal. Consequently, the dependency was removed
from the dependencyManagement section of the rest-server-base POM and
should be removed from the POM of any servers or libraries as it is
no longer required by Platform.

* Fixed a bug preventing V1 Events from being able to be used with HttpRequestEvents

* Check for duplicate classes in the dependency closure during builds

Starting at 0.59, any rest-server-base dependent projects will have a build
step added that ensures there are no duplicates of classes or resources on
the classpath.  Any duplicates will trigger a failure of the build and the
build output will include all the problematic classes or resources and which
packages they come from.  Using the dependency:tree build goal can help with
finding these conflicts and resolving them.

* Add JsonEventSerializer for external use

JsonEventSerializer serializes a single event in v2 format using a JsonGenerator.
The existing JsonEventWriter is not easily consumed from external projects.

* Add support for Rack servers to be able to announce with Discovery

Starting with 0.59, the configuration property "rackserver.announcement" will
set the name for the rack server to announce to discovery.  The remaining
configuration to announce with discovery is identical to rest-server-base
parented projects.

Platform 0.58

* Fixed bug that prevents Rack applications from starting

* As of release 0.55, the HttpServerModule has additional dependencies:

 - HttpEventModule
 - DiscoveryModule
 - JsonModule


Platform 0.57

* Fixed bug that prevents ServiceInventory from refreshing periodically

Platform 0.56

* Fixed bug that causes HttpRequestEvents to not be published

Platform 0.55

* In this release we have upgraded the following dependencies

  - Jackson 1.9.5

* HTTP request events

We now record an event for each HTTP request processed.  The HTTP request logging and
new event system now properly support the X-FORWARDED-FOR and X-FORWARDED-PROTO headers.

* Redesigned HTTP client

The existing HTTP client interface has been renamed to AsyncHttpClient and a new synchronous
HTTP client interface has been added in its place.  Additionally, the underlying HTTP client
engine has been replaced with Apache HTTP Components.

The HTTP client is still experimental.


Platform 0.54

This release removed the use of DocLava for generating javadocs for projects rest-server-base.
It was triggering a bug in javadoc that prevented some projects from building successfully.


Platform 0.53

* In this release we have upgraded the following dependencies

  - Jetty 8.1.1
  - Guava 11.0.2

Jetty 8.0.3 has a bug where connections will leak in CLOSE_WAIT state if clients hang up
prematurely.

* Testing servlet filters

When developing servlet filters for use with the platform HTTP server, it is now possible
to test these filters inside the TestingHttpServer. Bind the TestingHttpServerModule into your
test injector along with the module that binds your servlet filter.

* Rack packaging (JRuby on Rails)

The rack packaging has been substantially updated with many changes:

  - rewritten launcher that supports the new node config file
  - support only Rails 3.1+ with asset pipeline
  - add support for JMX over HTTP
  - use Bundler to require dependencies when starting application
  - no creation of .bundle directory when packaging gems
  - various bug fixes including PATH_INFO, logging, locking, resources

This release requires Rails 3.1+ rather than supporting arbitrary rack
applications. It also requires the build machine to have a Ruby installation
with all of the application gems installed. This is a temporary restriction
and will be fixed in future releases.

The build process runs "bundle exec rake assets:precompile". Please verify
that this command succeeds before running the build. The following config
change in config/application.rb is likely required to prevent the command
from trying to connect to the configured production database:

  # Only partially load application when precompiling assets
  config.assets.initialize_on_precompile = false

The following config changes are also required for production mode in
config/environments/production.rb:

  # Serve static assets directly from Rails
  config.serve_static_assets = true

  # Enable threaded mode
  config.threadsafe!

Future versions of the rack packaging may configure these automatically.


Platform 0.52

* Admin Http Server thread pool

The thread pool for the admin http server (for jmx over http) listener has been
separated from the main http thread pool to prevent DoS if all http threads in the main
pool get stuck.

The pool size can be controlled via the http-server.admin.threads.min and http-server.admin.threads.max
configuration properties.

* Configurable http client timeouts

Connection and read timeouts for http client are now configurable. For Discovery client, use
discovery.http-client.connect-timeout and discovery.http-client.read-timeout. For Event client,
use event.http-client.connect-timeout and event.http-client.read-timeout.

* Add external address to node info

Added node.external-address property to specify the external address (e.g., Internet routable)
to the JVM. HTTP and JMX services are announced using the existing name and a '-external' name,
so external clients can easily find the server.

Platform 0.51

* Trace token support for http requests

The http server can now deal with request trace tokens passed in via a
request header (X-Proofpoint-TraceToken). The trace token is recorded
in the request logs and is made available to application code via a
TraceTokenManager object. If no token is provided, a new one is created
automatically.

To enable this functionality, simply add a dependency to
com.proofpoint.platform:trace-token and add TraceTokenModule to the list of
guice modules for your application.

* Event fields support Map and Multimap

In addition to Iterable, the event client now supports event fields of type
java.util.Map and com.google.common.collect.Multimap. The map key type must
be java.lang.String, while the value type can be any standard supported type
or nested type (i.e. any type that is supported by Iterable).


Platform 0.50

* Library Upgrades

In this release we have upgraded the following dependencies

  - Guava 10.0.1
  - TestNG 6.2.1
  - Joda time 2.0
  - CGlib 2.2.2
  - Hibernate validation 4.2.0.Final
  - log4j-over-slf4j 1.6.2
  - Logback 0.9.30

* Log configuration via JMX

Log levels can now be configured via JMX under an mbean named
com.proofpoint.log:name=Logging. Enable this by adding LogJmxModule to your
Guice modules. The AllLevels attribute returns all explicitly configured
loggers (it excludes those with an inherited level).


Platform 0.49, Oct 14th 2011

* Library Upgrades

In this release we have upgraded the following dependencies

  - Jetty 8.0.3
  - Jackson 1.9.1

* Http server critical bugs

There are a number of bugs in versions of Jetty prior to 8.0.3 that can cause
the server to spin in a busy loop when using SSL or leak file descriptors under
certain conditions.

* Admin port

The http-based jmx connector now runs on an alternate admin port to avoid polluting
the request logs and stats when monitoring the server through jmx. For backwards
compatibility, the http listener is bound to a random port. The binding can be
overriden via the http-server.admin.port property and can be turned off via
http-server.admin.enabled.

* Service inventory

Discovery client now finds the location of available discovery servers by calling
out to a service inventory API. The location of the service inventory API is specified
via the service-inventory.uri configuration property and is provided automatically
when deploying with recent snapshot versions of Galaxy.

This feature is experimental, so the old discovery.uri property is still supported.

* PGP signing of artifacts

Projects that inherit from rest-server-base are now automatically signed with PGP on
release. To get this working, the release machine and account needs to have a PGP key
and agent configured.

See http://www.sonatype.com/people/2010/01/how-to-generate-pgp-signatures-with-maven/
for more information.

* Http server request stats

The http server now exposes additional request stats via JMX under an mbean named
com.proofpoint.http:name=RequestStats.

The available stats include:
- Request count
    - Total
    - 1-minute, 5-minute and 15-minute exponentially-weighted moving average requests
      per second
- Bytes Read/Written to connection
    - Total (since server start)
    - Exponentially-weighted per-request mean, min, max, percentiles (50, 90, 99, 99.9)
      with a bias towards the past 5 minutes
    - 1-minute, 5-minute and 15-minute exponentially-weighted moving average bytes
      per second
- Request time (ms)
    - Total (since server start)
    - Exponentially-weighted per-request mean, min, max, percentiles (50, 90, 99, 99.9)
      with a bias towards the past 5 minutes
    - 1-minute, 5-minute and 15-minute exponentially-weighted moving average bytes
      per second

* Http client request stats

Event and discovery clients now expose http request stats via JMX under the
com.proofpoint.discovery.client:name=DiscoveryClient and
com.proofpoint.event.client:name=EventClient mbeans.

The available stats include:
- Request count
    - Total
    - 1-minute, 5-minute and 15-minute exponentially-weighted moving average requests
      per second
- Bytes Read/Written to connection
    - Total (since server start)
    - Exponentially-weighted per-request mean, min, max, percentiles (50, 90, 99, 99.9)
      with a bias towards the past 5 minutes
    - 1-minute, 5-minute and 15-minute exponentially-weighted moving average bytes
      per second
- Request scheduling time (ms) -- time for request to get picked up by an available worker thread.
    - Total (since server start)
    - Exponentially-weighted per-request mean, min, max, percentiles (50, 90, 99, 99.9)
      with a bias towards the past 5 minutes
    - 1-minute, 5-minute and 15-minute exponentially-weighted moving average bytes
      per second
- Scheduling time (ms) -- time for request to get picked up by an available worker thread.
    - Total (since server start)
    - Exponentially-weighted per-request mean, min, max, percentiles (50, 90, 99, 99.9)
      with a bias towards the past 5 minutes
    - 1-minute, 5-minute and 15-minute exponentially-weighted moving average bytes
      per second
- Request time (ms) -- time to send request data to remote server
    - Total (since server start)
    - Exponentially-weighted per-request mean, min, max, percentiles (50, 90, 99, 99.9)
      with a bias towards the past 5 minutes
    - 1-minute, 5-minute and 15-minute exponentially-weighted moving average bytes
      per second
- Response time (ms) -- time to read response
    - Total (since server start)
    - Exponentially-weighted per-request mean, min, max, percentiles (50, 90, 99, 99.9)
      with a bias towards the past 5 minutes
    - 1-minute, 5-minute and 15-minute exponentially-weighted moving average bytes
      per second


Platform 0.48, Oct 5th 2011

* Library Upgrades

In this release we have upgraded the following dependencies

  - Guava 10.0
  - Hector 0.8.0-2
  - Jersey 1.9.1
  - Jetty 8.0.1

Note: we have banned all prior versions of Guava since the former versioning
names are not understood by maven and can result in invalid combinations of
dependencies.

* Jmx over HTTP

One of the major problems we have with supporting our servers in a production
environment is accessing JMX through the firewall.  JMX uses RMI by default
and RMI binds to two random ports, so we can run multiple servers on the same
instance.  This configuration annoyance is compounded by the bidirectional
nature of the RMI protocol.  When an RMI object is published, it encodes the
local address of the server on which the object is running.  In EC2, each
server has a private IP for use within EC2 and a public address which we use for
connecting from out side of EC2.  Since the RMI object can only contain one
address, we must choose between JMX being internally or externally accessible.

We have eliminated both of these problems by writing a HTTP based JMX Remoteing
(JSR 160) connector. To add this to your server, simply add the JmxHttpRpcModule
to the Guice modules.  The following command will connect jvisualvm to the server:

  jvisualvm --cp:a jmx-http-rpc-experimental.jar \
      --openjmx service:jmx:http://<host>:<port>

Note: You must install the VisualVM-MBean plugin to see mbeans in jvisualvm



Platform 0.47, Sept 29th 2011

* EventClient and DiscoveryClient

After running some of our servers under load, we have found major memory leaks
in EventClient and DiscoveryClient due to the AsyncHttpClient.  Unfortunately,
these leaks are difficult to fix due to the complexity of this code base, so we
have replaced the use of AsyncHttpClient in these libraries with the
experimental http client.

* HttpClient

We have written a vastly simplified event client interface that supports only the
features needed by EventClient and DiscoveryClient.  The current
implementation uses java.net.URL internally but we expect this to change.  This
code base is under active development and should not be used outside of the
platform until it is stabilizes.

Platform 0.46, Sept 26th 2011

* Launcher script

This release addresses one of the recent problems we've had with our servers
running in Galaxy.  Galaxy splits the installation directory, which contains
our configuration files, from the data directory where the Java process runs.
This split makes it easy for Galaxy to upgrade servers without losing
persistent server data, but this split means it is impossible for the Java
program to locate configuration files in the installation etc directory.  We
have fixed this problem by having the launcher script symlink the etc
directory from the installation directory into the data directory, so the Java
process can find the configuration using a relative path.


Platform 0.45, Sept 22th 2011

* oss.sonatype.org

We are pleased to announce that starting with this release, all artifacts are
published to Maven Central.  You can search for our artifacts here:

  http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.proofpoint.platform%22

* HttpServer

We have added the request size to the http server log.  The new log line format
follows:

  timeStamp remoteAddress method uri user agent status contentRead contentCount requestTime

As a comparison the previous log line format was:

  timeStamp remoteAddress method uri user agent status contentCount requestTime

Additionally, we have reenabled SSL renegotiation since the underlying JVM bug
has been fixed.

* Launcher script

Starting with this release, the preferred method for passing node specific
information (e.g., id, environment, and pool) to a server is the --node-config
command line option.  The argument to this option must point to a file
containing key-value pairs encoded as 'key=value'.  The properties in this file
are simply added to the Java command line as -D parameters when launching the
server.  Parameters can still be passed to the server using -D parameters on
the launcher, and these will override any parameters in the node config file.

* JRuby on Rails

It is now possible to package a Rails application just like any other Java
platform application.  The packaged application will use the platform http
server, logging, and over time we will extend the integration to support other
platform services.  An instructional guide is currently under review and will
be included soon.


and run rack applications, such as rails, using the
platform http server.  The platform logger is automatically provided to rack and rails, and other
platform facilities can be used from within JRuby.  Simply set
rack-server-base-experimental as your parent pom, and you gain many of the same
features that exist in the rest-server-base parent pom.  An instructional guide is
currently under review and will be included soon.

* Event Client v2

The event client for the event v2 protocol has been mostly rewritten to fix
various bugs and annoyances.  Additionally, we have have expanded the allowed
event fields to include java.util.Iterable and nested simple event types.  For
Iterable, any supported type is allowed for the elements except Iterable.
Nested event types, can be any event type without a special field (e.g.,
timestamp, uuid, or host) since these are only allowed in the envelope
of the protocol.  For a full example see:

  com.proofpoint.event.client.NestedDummyEventClass

* Embedded Cassandra

Cassandra has been upgraded to 0.8.5 which addresses many internal bugs (see
https://svn.apache.org/repos/asf/cassandra/tags/cassandra-0.8.5/CHANGES.txt
for more information).  Additional, work has been on startup reliability and
timeout configuration.

One backwards incompatible change is the default partitioner is now
ByteOrderedPartitioner instead of RandomPartitioner since most of our
application are using range queries.

* AsyncHttpClient

We have upgraded AsyncHttpClient to version 1.6.5, but since this version still
contains a memory leak we have removed it from the event client.  We are
several evaluating long term solutions to the memory leak and hope to have one
implemented in the next release.

* DataSize helper methods

The toBytes() and roundTo(Unit) helper method have been added to DataSize for
easily converting the size to a long.  These methods will throw an exception if
the size is bigger than a long in the specified unit.

* Removed Discovery JDBC

The experimental discovery based JDBC driver has been removed.  This was
originally introduced for supporting database discovery to rails, but this
feature has been rewritten in much simpler pure Ruby.

* Bug fixes
    - System out and err redirect to logging does not flush
    - Fixed race condition in embedded Cassandra lifecycle
    - Fixed error reporting in event client
    - Fixed launcher issues with spawn using 'sh -c' on Linux


Platform 0.44, Sept 22th 2011

* Bad release

Don't use this release, it is bad.

Platform 0.43, Jun 10th 2011

* JRuby on Rails integration

We've started the work support JRuby on Rails in the platform by adding a
servlet based implementation of Rack.  Work will continue in future releases.


* Bug fixes
    - Discovery client fails to reschedule refresh job in some cases




Platform 0.42, May 24th 2011

* Embedded Cassandra and testing utilities

The code is part of the cassandra-experimental module
(com.proofpoint.platform:cassandra-experimental:0.42). The server is enabled by
adding CassandraModule to your Guice injector. Configuration for the server is
encapsulated in CassandraServerConfig. Code that needs to talk to the cassandra
server (e.g., Hector) should depend on CassandraServerInfo, which exposes a
method for obtaining the RPC port that Cassandra listens on.

Here's an example of how to run a simple server with an embedded cassandra instance:


       Bootstrap bootstrap = new Bootstrap(new NodeModule(), new CassandraModule());

       try {
           Injector injector = bootstrap.initialize();
           CassandraServerInfo info = injector.getInstance(CassandraServerInfo.class);
           log.info("Cassandra server listening on port " + info.getRpcPort());
       }
       catch (Throwable e) {
           log.error(e);
           // Cassandra creates non-daemon threads that will prevent the vm from shutting down
           System.exit(1);
       }



We've also added some utilities to simplify unit testing of code that talks to
Cassandra. It is important to keep in mind that due to how Cassandra is
written, there can only be one embedded instance per VM, and it can only be
started once during the lifetime of the VM.

To use Cassandra in unit tests, use CassandraServerSetup to initialize the
embedded instance. This should be done in @BeforeSuite and @AfterSuite methods
that call CassandraServerSetup.tryInitialize() and tryShutdown(), respectively.
It's important that this be done in every class that contains cassandra-based
tests. Otherwise, the initialization code  will only run if you include the
class with these methods in your unit test execution. TryInitialize() and
tryShutdown() are designed to properly handle calls from multiple
@Before/AfterSuite methods.

The server will be bound to a random port which can be obtained through the
CassandraServerInfo object. To get this object use either
CassandraServerSetup.getServerInfo() or TestingCassandraModule if your tests
require Guice.

* DataSize

We've introduced a DataSize class to the experimental module for dealing with
units of data in human-readable form (similar to Duration). It supports B, kB,
MB, GB, TB, PB and can handle conversions between these units. It's also fully
compatible with the configuration system.

* ValidationAssertions

We've also added some utilities to the experimental module to make easier to
test code that uses Bean Validation Framework annotations.
ValidationAssertions.assertValidates() and assertFailsValidation() can be used
to test that an object passes or fails validations as specified by its
annotations. Here's an example on how to use assertFailsValidation():

        assertFailsValidation(config, "maxAge", "may not be null", NotNull.class)

* Bug fixes

The following issues have been fixed:
  - Discovery client fails when consuming static announcements
  - MySQL connection timeouts using the wrong unit (ms vs s)
  - Jar manifest using the wrong file names when building snapshot versions