HttpSerializer

java.lang.Object
- net.opentsdb.tsd.HttpSerializer

```
public abstract class HttpSerializer
extends Object
```
Abstract base class for Serializers; plugins that handle converting requests and responses between OpenTSDB's internal data and various popular formats such as JSON, XML, OData, etc. They can also be used to accept inputs from existing collection systems such as CollectD.
The serializer workflow is as follows:
- Request comes in via the HTTP API
- The proper serializer is instantiated via:
  - Query string parameter "serializer=<shortName>"
  - If no query string parameter is found, the Content-Type is parsed
  - Otherwise the default serializer is used
- The request is routed to an RPC handler
- If the handler needs details for a complex request, it calls on the proper serializer's "parseX" method to get a query object
- The RPC handler fetches and organizes the data
- The handler passes the data to the proper serializer's "formatX" method
- The serializer formats the data and sends it back as a byte array
Warning: Every HTTP request will instantiate a new serializer object (except for a few that don't require it) so please avoid creating heavy objects in the constructor, parse or format methods. Instead, use the initialize(net.opentsdb.core.TSDB) method to instantiate thread-safe, static objects that you need for de/serializtion. It will be called once on TSD startup.
Note: If a method needs to throw an exception due to user error, such as missing data or a bad request, throw a BadRequestException with a status code, error message and optional details.
Runtime exceptions, anything that goes wrong internally with your serializer, will be returned with a 500 Internal Server Error status.
Note: You can change the HTTP status code before returning from a "formatX" method by accessing "this.query.response().setStatus()" and providing an HttpResponseStatus object.
Note: You can also set response headers via "this.query.response().setHeader()". The "Content-Type" header will be set automatically with the "response_content_type" field value that can be overridden by the plugin. HttpQuery will also set some other headers before returning
Since:

2.0

Field Summary

Fields
Modifier and Type	Field and Description
`protected net.opentsdb.tsd.HttpQuery`	`query` The query used for accessing the DefaultHttpResponse object and other information
`protected String`	`request_content_type` Content type to use for matching a serializer to incoming requests
`protected String`	`response_content_type` Content type to return with data from this serializer

Constructor Summary

Constructors
Constructor and Description
`HttpSerializer()` Empty constructor required for plugin operation
`HttpSerializer(net.opentsdb.tsd.HttpQuery query)` Constructor that serializers must implement.

Method Summary

Methods
Modifier and Type	Method and Description
`org.jboss.netty.buffer.ChannelBuffer`	`formatAggregatorsV1(Set<String> aggregators)` Format the list of implemented aggregators
`org.jboss.netty.buffer.ChannelBuffer`	`formatAnnotationV1(Annotation note)` Format an annotation object
`org.jboss.netty.buffer.ChannelBuffer`	`formatBranchV1(Branch branch)` Format a single Branch object
`org.jboss.netty.buffer.ChannelBuffer`	`formatConfigV1(Config config)` Format the running configuration
`org.jboss.netty.buffer.ChannelBuffer`	`formatDropCachesV1(Map<String,String> response)` Format a response from the DropCaches call
`org.jboss.netty.buffer.ChannelBuffer`	`formatErrorV1(net.opentsdb.tsd.BadRequestException exception)` Format a bad request exception, indicating an invalid request from the user
`org.jboss.netty.buffer.ChannelBuffer`	`formatErrorV1(Exception exception)` Format an internal error exception that was caused by the system Should return a 500 error
`org.jboss.netty.buffer.ChannelBuffer`	`formatNotFoundV1()` Formats a 404 error when an endpoint or file wasn't found
`org.jboss.netty.buffer.ChannelBuffer`	`formatPutV1(Map<String,Object> results)` Formats the results of an HTTP data point storage request
`org.jboss.netty.buffer.ChannelBuffer`	`formatQueryV1(TSQuery query, List<DataPoints[]> results, List<Annotation> globals)` Format the results from a timeseries data query
`org.jboss.netty.buffer.ChannelBuffer`	`formatSearchResultsV1(SearchQuery results)` Format the response from a search query
`org.jboss.netty.buffer.ChannelBuffer`	`formatSerializersV1()` Format the serializers status map
`org.jboss.netty.buffer.ChannelBuffer`	`formatStatsV1(List<IncomingDataPoint> stats)` Format a list of statistics
`org.jboss.netty.buffer.ChannelBuffer`	`formatSuggestV1(List<String> suggestions)` Formats a suggestion response
`org.jboss.netty.buffer.ChannelBuffer`	`formatTreeCollisionNotMatchedV1(Map<String,String> results, boolean is_collisions)` Format a map of one or more TSUIDs that collided or were not matched
`org.jboss.netty.buffer.ChannelBuffer`	`formatTreeRuleV1(TreeRule rule)` Format a single TreeRule object
`org.jboss.netty.buffer.ChannelBuffer`	`formatTreesV1(List<Tree> trees)` Format a list of tree objects.
`org.jboss.netty.buffer.ChannelBuffer`	`formatTreeTestV1(HashMap<String,HashMap<String,Object>> results)` Format the results of testing one or more TSUIDs through a tree's ruleset
`org.jboss.netty.buffer.ChannelBuffer`	`formatTreeV1(Tree tree)` Format a single tree object
`org.jboss.netty.buffer.ChannelBuffer`	`formatTSMetaV1(TSMeta meta)` Format a single TSMeta object
`org.jboss.netty.buffer.ChannelBuffer`	`formatUidAssignV1(Map<String,TreeMap<String,String>> response)` Format a response from the Uid Assignment RPC
`org.jboss.netty.buffer.ChannelBuffer`	`formatUidMetaV1(UIDMeta meta)` Format a single UIDMeta object
`org.jboss.netty.buffer.ChannelBuffer`	`formatVersionV1(Map<String,String> version)` Format a hash map of information about the OpenTSDB version
`abstract void`	`initialize(TSDB tsdb)` Initializer called one time when the TSD starts up and loads serializer plugins.
`Annotation`	`parseAnnotationV1()` Parses an annotation object
`List<IncomingDataPoint>`	`parsePutV1()` Parses one or more data points for storage
`TSQuery`	`parseQueryV1()` Parses a timeseries data query
`SearchQuery`	`parseSearchQueryV1()` Parses a SearchQuery request
`HashMap<String,String>`	`parseSuggestV1()` Parses a suggestion query
`List<TreeRule>`	`parseTreeRulesV1()` Parses one or more tree rules
`TreeRule`	`parseTreeRuleV1()` Parses a single TreeRule object
`Map<String,Object>`	`parseTreeTSUIDsListV1()` Parses a tree ID and optional list of TSUIDs to search for collisions or not matched TSUIDs.
`Tree`	`parseTreeV1()` Parses a single Tree object
`TSMeta`	`parseTSMetaV1()` Parses a single TSMeta object
`HashMap<String,List<String>>`	`parseUidAssignV1()` Parses a list of metrics, tagk and/or tagvs to assign UIDs to
`UIDMeta`	`parseUidMetaV1()` Parses a single UIDMeta object
`String`	`requestContentType()`
`String`	`responseContentType()`
`abstract String`	`shortName()` The simple name for this serializer referenced by users.
`abstract com.stumbleupon.async.Deferred<Object>`	`shutdown()` Called when the TSD is shutting down so implementations can gracefully close their objects or connections if necessary
`abstract String`	`version()` The version of this serializer plugin in the format "MAJOR.MINOR.MAINT" The MAJOR version should match the major version of OpenTSDB, e.g.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - request_content_type
```
protected String request_content_type
```
    Content type to use for matching a serializer to incoming requests
  - response_content_type
```
protected String response_content_type
```
    Content type to return with data from this serializer
  - query
```
protected final net.opentsdb.tsd.HttpQuery query
```
    The query used for accessing the DefaultHttpResponse object and other information
- Constructor Detail
  - HttpSerializer
```
public HttpSerializer()
```
    Empty constructor required for plugin operation
  - HttpSerializer
```
public HttpSerializer(net.opentsdb.tsd.HttpQuery query)
```
    Constructor that serializers must implement. This is how each plugin will get the request content and have the option to set headers or a custom status code in the response.
    Note: A new serializer is instantiated for every HTTP connection, so don't do any heavy object creation here. Instead, use the initialize(net.opentsdb.core.TSDB) method to setup static, thread-safe objects if you need stuff like that
    
    Parameters:
    query -
- Method Detail
  - initialize
```
public abstract void initialize(TSDB tsdb)
```
    Initializer called one time when the TSD starts up and loads serializer plugins. You should use this method to setup static, thread-safe objects required for parsing or formatting data.
    
    Parameters:
    tsdb - The TSD this plugin belongs to. Use it to fetch config data if require.
  - shutdown
```
public abstract com.stumbleupon.async.Deferred<Object> shutdown()
```
    Called when the TSD is shutting down so implementations can gracefully close their objects or connections if necessary
    
    Returns:
    An object, usually a Boolean, used to wait on during shutdown
  - version
```
public abstract String version()
```
    The version of this serializer plugin in the format "MAJOR.MINOR.MAINT" The MAJOR version should match the major version of OpenTSDB, e.g. if the plugin is associated with 2.0.1, your version should be 2.x.x.
    
    Returns:
    the version as a String
  - shortName
```
public abstract String shortName()
```
    The simple name for this serializer referenced by users. The name should be lower case, all one word without any odd characters so it can be used in a query string. E.g. "json" or "xml" or "odata"
    
    Returns:
    the name of the serializer
  - requestContentType
```
public String requestContentType()
```
    Returns:
    the incoming content type
  - responseContentType
```
public String responseContentType()
```
    Returns:
    the outgoing content type
  - parsePutV1
```
public List<IncomingDataPoint> parsePutV1()
```
    Parses one or more data points for storage
    
    Returns:
    an array of data points to process for storage
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - parseSuggestV1
```
public HashMap<String,String> parseSuggestV1()
```
    Parses a suggestion query
    
    Returns:
    a hash map of key/value pairs
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - parseUidAssignV1
```
public HashMap<String,List<String>> parseUidAssignV1()
```
    Parses a list of metrics, tagk and/or tagvs to assign UIDs to
    
    Returns:
    as hash map of lists for the different types
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - parseSearchQueryV1
```
public SearchQuery parseSearchQueryV1()
```
    Parses a SearchQuery request
    
    Returns:
    The parsed search query
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - parseQueryV1
```
public TSQuery parseQueryV1()
```
    Parses a timeseries data query
    
    Returns:
    A TSQuery with data ready to validate
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - parseUidMetaV1
```
public UIDMeta parseUidMetaV1()
```
    Parses a single UIDMeta object
    
    Returns:
    the parsed meta data object
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - parseTSMetaV1
```
public TSMeta parseTSMetaV1()
```
    Parses a single TSMeta object
    
    Returns:
    the parsed meta data object
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - parseTreeV1
```
public Tree parseTreeV1()
```
    Parses a single Tree object
    
    Returns:
    the parsed tree object
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - parseTreeRuleV1
```
public TreeRule parseTreeRuleV1()
```
    Parses a single TreeRule object
    
    Returns:
    the parsed rule object
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - parseTreeRulesV1
```
public List<TreeRule> parseTreeRulesV1()
```
    Parses one or more tree rules
    
    Returns:
    A list of one or more rules
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - parseTreeTSUIDsListV1
```
public Map<String,Object> parseTreeTSUIDsListV1()
```
    Parses a tree ID and optional list of TSUIDs to search for collisions or not matched TSUIDs.
    
    Returns:
    A map with "treeId" as an integer and optionally "tsuids" as a List
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - parseAnnotationV1
```
public Annotation parseAnnotationV1()
```
    Parses an annotation object
    
    Returns:
    An annotation object
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - formatPutV1
```
public org.jboss.netty.buffer.ChannelBuffer formatPutV1(Map<String,Object> results)
```
    Formats the results of an HTTP data point storage request
    Parameters:
    results - A map of results. The map will consist of:
    success - (long) the number of successfully parsed datapoints
    
    failed - (long) the number of datapoint parsing failures
    
    errors - (ArrayList>) an optional list of datapoints that had errors. The nested map has these fields:
    error - (String) the error that occurred
    
    datapoint - (IncomingDatapoint) the datapoint that generated the error
    Returns:
    A ChannelBuffer object to pass on to the caller
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - formatSuggestV1
```
public org.jboss.netty.buffer.ChannelBuffer formatSuggestV1(List<String> suggestions)
```
    Formats a suggestion response
    
    Parameters:
    suggestions - List of suggestions for the given type
    
    Returns:
    A ChannelBuffer object to pass on to the caller
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - formatSerializersV1
```
public org.jboss.netty.buffer.ChannelBuffer formatSerializersV1()
```
    Format the serializers status map
    
    Returns:
    A ChannelBuffer object to pass on to the caller
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - formatAggregatorsV1
```
public org.jboss.netty.buffer.ChannelBuffer formatAggregatorsV1(Set<String> aggregators)
```
    Format the list of implemented aggregators
    
    Parameters:
    aggregators - The list of aggregation functions
    
    Returns:
    A ChannelBuffer object to pass on to the caller
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - formatVersionV1
```
public org.jboss.netty.buffer.ChannelBuffer formatVersionV1(Map<String,String> version)
```
    Format a hash map of information about the OpenTSDB version
    
    Parameters:
    version - A hash map with version information
    
    Returns:
    A ChannelBuffer object to pass on to the caller
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - formatDropCachesV1
```
public org.jboss.netty.buffer.ChannelBuffer formatDropCachesV1(Map<String,String> response)
```
    Format a response from the DropCaches call
    
    Parameters:
    response - A hash map with a response
    
    Returns:
    A ChannelBuffer object to pass on to the caller
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - formatUidAssignV1
```
public org.jboss.netty.buffer.ChannelBuffer formatUidAssignV1(Map<String,TreeMap<String,String>> response)
```
    Format a response from the Uid Assignment RPC
    
    Parameters:
    response - A map of lists of pairs representing the results of the assignment
    
    Returns:
    A ChannelBuffer object to pass on to the caller
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - formatQueryV1
```
public org.jboss.netty.buffer.ChannelBuffer formatQueryV1(TSQuery query,
                                                 List<DataPoints[]> results,
                                                 List<Annotation> globals)
```
    Format the results from a timeseries data query
    
    Parameters:
    query - The TSQuery object used to fetch the results
    results - The data fetched from storage
    globals - An optional list of global annotation objects
    
    Returns:
    A ChannelBuffer object to pass on to the caller
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - formatUidMetaV1
```
public org.jboss.netty.buffer.ChannelBuffer formatUidMetaV1(UIDMeta meta)
```
    Format a single UIDMeta object
    
    Parameters:
    meta - The UIDMeta object to serialize
    
    Returns:
    A ChannelBuffer object to pass on to the caller
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - formatTSMetaV1
```
public org.jboss.netty.buffer.ChannelBuffer formatTSMetaV1(TSMeta meta)
```
    Format a single TSMeta object
    
    Parameters:
    meta - The TSMeta object to serialize
    
    Returns:
    A ChannelBuffer object to pass on to the caller
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - formatBranchV1
```
public org.jboss.netty.buffer.ChannelBuffer formatBranchV1(Branch branch)
```
    Format a single Branch object
    
    Parameters:
    branch - The branch to serialize
    
    Returns:
    A ChannelBuffer object to pass on to the caller
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - formatTreeV1
```
public org.jboss.netty.buffer.ChannelBuffer formatTreeV1(Tree tree)
```
    Format a single tree object
    
    Parameters:
    tree - tree to serialize
    
    Returns:
    A ChannelBuffer object to pass on to the caller
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - formatTreesV1
```
public org.jboss.netty.buffer.ChannelBuffer formatTreesV1(List<Tree> trees)
```
    Format a list of tree objects. Note that the list may be empty if no trees were present.
    
    Parameters:
    trees - A list of one or more trees to serialize
    
    Returns:
    A ChannelBuffer object to pass on to the caller
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - formatTreeRuleV1
```
public org.jboss.netty.buffer.ChannelBuffer formatTreeRuleV1(TreeRule rule)
```
    Format a single TreeRule object
    
    Parameters:
    rule - The rule to serialize
    
    Returns:
    A ChannelBuffer object to pass on to the caller
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - formatTreeCollisionNotMatchedV1
```
public org.jboss.netty.buffer.ChannelBuffer formatTreeCollisionNotMatchedV1(Map<String,String> results,
                                                                   boolean is_collisions)
```
    Format a map of one or more TSUIDs that collided or were not matched
    
    Parameters:
    results - The list of results. Collisions: key = tsuid, value = collided TSUID. Not Matched: key = tsuid, value = message about non matched rules.
    is_collisions - Whether or the map is a collision result set (true) or a not matched set (false).
    
    Returns:
    A ChannelBuffer object to pass on to the caller
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - formatTreeTestV1
```
public org.jboss.netty.buffer.ChannelBuffer formatTreeTestV1(HashMap<String,HashMap<String,Object>> results)
```
    Format the results of testing one or more TSUIDs through a tree's ruleset
    
    Parameters:
    results - The list of results. Main map key is the tsuid. Child map: "branch" : Parsed branch result, may be null "meta" : TSMeta object, may be null "messages" : An ArrayList of one or more messages
    
    Returns:
    A ChannelBuffer object to pass on to the caller
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - formatAnnotationV1
```
public org.jboss.netty.buffer.ChannelBuffer formatAnnotationV1(Annotation note)
```
    Format an annotation object
    
    Parameters:
    note - The annotation object to format
    
    Returns:
    A ChannelBuffer object to pass on to the caller
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - formatStatsV1
```
public org.jboss.netty.buffer.ChannelBuffer formatStatsV1(List<IncomingDataPoint> stats)
```
    Format a list of statistics
    
    Parameters:
    stats - The statistics list to format
    
    Returns:
    A ChannelBuffer object to pass on to the caller
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - formatSearchResultsV1
```
public org.jboss.netty.buffer.ChannelBuffer formatSearchResultsV1(SearchQuery results)
```
    Format the response from a search query
    
    Parameters:
    results - The query (hopefully filled with results) to serialize
    
    Returns:
    A ChannelBuffer object to pass on to the caller
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - formatConfigV1
```
public org.jboss.netty.buffer.ChannelBuffer formatConfigV1(Config config)
```
    Format the running configuration
    
    Parameters:
    config - The running config to serialize
    
    Returns:
    A ChannelBuffer object to pass on to the caller
    
    Throws:
    
    BadRequestException - if the plugin has not implemented this method
  - formatNotFoundV1
```
public org.jboss.netty.buffer.ChannelBuffer formatNotFoundV1()
```
    Formats a 404 error when an endpoint or file wasn't found
    WARNING: If overriding, make sure this method catches all errors and returns a byte array with a simple string error at the minimum
    
    Returns:
    A standard JSON error
  - formatErrorV1
```
public org.jboss.netty.buffer.ChannelBuffer formatErrorV1(net.opentsdb.tsd.BadRequestException exception)
```
    Format a bad request exception, indicating an invalid request from the user
    WARNING: If overriding, make sure this method catches all errors and returns a byte array with a simple string error at the minimum
    
    Parameters:
    exception - The exception to format
    
    Returns:
    A standard JSON error
  - formatErrorV1
```
public org.jboss.netty.buffer.ChannelBuffer formatErrorV1(Exception exception)
```
    Format an internal error exception that was caused by the system Should return a 500 error
    WARNING: If overriding, make sure this method catches all errors and returns a byte array with a simple string error at the minimum
    
    Parameters:
    exception - The system exception to format
    
    Returns:
    A standard JSON error

Class HttpSerializer

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

request_content_type

response_content_type

query

Constructor Detail

HttpSerializer

HttpSerializer

Method Detail

initialize

shutdown

version

shortName

requestContentType

responseContentType

parsePutV1

parseSuggestV1

parseUidAssignV1

parseSearchQueryV1

parseQueryV1

parseUidMetaV1

parseTSMetaV1

parseTreeV1

parseTreeRuleV1

parseTreeRulesV1

parseTreeTSUIDsListV1

parseAnnotationV1

formatPutV1

formatSuggestV1

formatSerializersV1

formatAggregatorsV1

formatVersionV1

formatDropCachesV1

formatUidAssignV1

formatQueryV1

formatUidMetaV1

formatTSMetaV1

formatBranchV1

formatTreeV1

formatTreesV1

formatTreeRuleV1

formatTreeCollisionNotMatchedV1

formatTreeTestV1

formatAnnotationV1

formatStatsV1

formatSearchResultsV1

formatConfigV1

formatNotFoundV1

formatErrorV1

formatErrorV1