Using the Adapter SDK
This section outlines the development process for writing custom adapters using the Adapter SDK for
Mashery Local Traffic Manager. This section also provides the list of areas of extension provided in the
SDK, along with code samples to illustrate the extension process.
Adapter SDK Package
The Adapter SDK defines the Traffic Manager domain model, tools and APIs and provides extension points to inject custom code in the processing of a call made to the Traffic Manager.
DIY SDK adapters need to be coded and compiled using JDK 1.6 or lower.
●
●
The Adapter SDK package contains the following:
TIBCO Mashery Domain SDK
TIBCO Mashery Infrastructure SDK
TIBCO Mashery Domain SDK
TIBCO Mashery Domain SDK packaged in com.mashery.trafficmanager.sdk identifies the traffic manager SDK and provides access to the TIBCO Mashery domain model which includes key objects such as Members, Applications, Developer Classes, Keys, Packages.
TIBCO Mashery Infrastructure SDK
TIBCO Mashery Infrastructure SDK provides the ability to handle infrastructure features and contains the following:
●
●
TIBCO Mashery HTTP Provider
The HTTP provider packaged as com.mashery.http provides HTTP Request/Response processing capability and tools to manipulate the HTTP Request, Response, their content and headers.
TIBCO Mashery Utility
The utility packaged as com.mashery.util provides utility code which handles frequently occurring logic such as string manipulations, caching, specialized collection handling, and logging.
SDK Domain Model
The Traffic Manager domain model defines the elements of the Traffic Manager runtime.
The following table highlights some of the key elements:
Element
User
API
Description
A user or member subscribing to
APIs and accesses the APIs.
An API represents the service definition. A service definition has endpoints defined for it.
Usage
com.mashery.trafficmanager.model.User
com.mashery.trafficmanager.model.API
25
TIBCO Mashery
®
Local Installation and Configuration Guide for Docker
Element
Endpoint
Method
Package
Plan
Description Usage
An Endpoint is a central resource of an API managed within Mashery. It is a collection of configuration options that defines the inbound and outbound URI's, rules, transformations, cache control, security, etc. of a unique pathway of your API.
An Endpoint is specialized as either an API Endpoint or a Plan
Endpoint. This specialization provides context to whether or not the Endpoint is being used as part of a Plan or not.
●
●
●
Generic endpoint entity representation: com.mashery.trafficmanager.model.E
ndpoint
API endpoint entity representation: com.mashery.trafficmanager.model.A
PIEndpoint
Plan endpoint entity representation: com.mashery.trafficmanager.model.P
lanEndpoint
A method is a function that can be called on an endpoint and represents the method currently being accessed/requested from the
API request. A method could have rate and throttle limits specified on it to dictate the volume of calls made using a specific key to that method.
A Method is specialized as either an
API Method or Plan Method. The specialization provides context to whether or not the Method belong to a Plan.
●
●
●
Generic method entity representation: com.mashery.trafficmanager.model.M
ethod
API method entity representation: com.mashery.trafficmanager.model.A
PIMethod
Plan method entity representation: com.mashery.trafficmanager.model.P
lanMethod
A Package is a mechanism to bundle or group API capability allowing the API Manager to then offer these capabilities to customers/users based on various access levels and price points. A
Package represents a group of
Plans.
com.mashery.trafficmanager.model.Pack
age
A Plan is a collection of API endpoints, methods and response filters to group functionality so that
API Product Managers can manage access control and provide access to appropriate Plans to different users.
com.mashery.trafficmanager.model.Plan
26
TIBCO Mashery
®
Local Installation and Configuration Guide for Docker
27
Element
API Call
Key
Description
The API Call object is the complete transaction of the incoming request received by the Traffic Manager and the outgoing response as processed by the Traffic Manager. It provides an entry point into all other entities used in the execution of the request.
Usage
com.mashery.trafficmanager.model.core
.APICall
A key is an opaque string allowing a developer to access the API functionality. A key has rate and throttle controls defined on it and dictates the volume of calls that can be made to the API by the caller.
A Key can be specialized as an API key or Package Key. This specialization provides context to whether the key provides access to an API or a specific Plan in a
Package.
●
●
●
Generic key entity representation: com.mashery.trafficmanager.model.K
ey
API key entity representation: com.mashery.trafficmanager.model.A
PIKey
Package key entity representation: com.mashery.trafficmanager.model.P
ackageKey
Application An application is a developer artifact that is registered by the developer when he subscribes to an
API or a Package.
Rate
Constraint
A Rate Constraint specifies how the amount of traffic is managed by limiting the number of calls per a time period (hours, days, months) that may be received.
com.mashery.trafficmanager.model.Appl
ication com.mashery.trafficmanager.model.Rate
Constraint
Throttle
Constraint
Customer
Site
A Throttle Constraint specifies how the velocity of traffic is managed by limiting the number of calls per second that may be received.
com.mashery.trafficmanager.model.Thro
ttleConstraint
A customer specific area configured through the developer portal.
com.mashery.trafficmanager.model.Cust
omerSite
Extended Attributes
The traffic manager model allows defining name-value pairs on different levels of the model. The levels are identified here:
●
●
●
●
Application
Customer Site
Key (both API Key and Package Key)
Package
TIBCO Mashery
®
Local Installation and Configuration Guide for Docker
28
●
●
Plan
User
Pre and Post Processor Extension Points
This version of the SDK allows extensions for Processors only. This means that only pre and post processing of requests prior to invocation of the target host are allowed.
Listener Pattern
The extension API leverages a listener pattern to deliver callbacks to extension points to allow injecting custom logic.
A call made to the traffic manager is an invocation to a series of tasks. Each step in the workflow accomplishes a specific task to fulfill the call. The current API release only allows customization of the tasks prior to invoking the API server (pre-process) and post receipt of the response from the API server (post-process). The callback API handling these extensions is called a Processor.
The pre-process step allows a processor to receive a fully-formed HTTP request targeted to the API server. The processor is allowed to alter the headers or the body of the request prior to the request being made to the server. Upon completion of the request and receiving the response the Traffic Manager allows the processor to alter the response content and headers prior to the response flowing back through a series of exit tasks out to the client.
Event Types and Event
The transition of the call from one task to the next is triggered through ‘events’ and an event is delivered to any subscriber interested in receiving the event. The SDK supports two event-types which are delivered synchronously:
●
●
Pre-Process Event type: This event is used to trigger any pre-process task.
Post-Process Event type: This event is used to trigger any post-process task.
The subscribers in this case will be Processors registered in a specific manner with the Traffic Manager
API.
Event Listener API
The Traffic Manager SDK provides the following interface and is implemented by custom processors to receive Processor Events.
package com.mashery.trafficmanager.event.listener; import com.mashery.trafficmanager.event.model.TrafficEvent;
/*** Event listener interface which is implemented by listeners which wish to handle Traffic events. Traffic events will be delivered via this callback synchronously to handlers implementing the interface.
The implementers of this interface subscribe to events via annotations. E.g.
Processor events need to handle events by using annotations in the com.mashery.proxy.sdk.event.processor.annotation */ public interface TrafficEventListener {
/*** The event is delivered to this API @param event*/
void handleEvent(TrafficEvent event);
}
Implementing and Registering Processors
Writing custom processors involves the following general steps:
●
●
●
Downloading the SDK
Implementing the event listener
Implementing lifecycle callback handling
TIBCO Mashery
®
Local Installation and Configuration Guide for Docker
29
●
Adding libraries to the classpath
The following sections describe these steps in more detail.
Downloading the SDK
To download the SDK:
Procedure
1. Click Download SDK, as shown in the screen shot:
2. Use your favorite IDE and put the SDK jars in your classpath.
3. Create a project and a new java class. The details of that process are skipped here and assumed that the developer will use the relevant IDE documentation to accomplish this.
Implementing the Event Listener
To implement the event listener:
Procedure
1. Employ the Traffic Event Listener interface (introduced in
Event Listener API ) as shown in the
following example: package com.company.extension; public class CustomProcessor implements TrafficEventListener{
public void handleEvent(TrafficEvent event){
//write your custom code here
}
}
2. Annotate your code to ensure that the processor is identified correctly for callbacks on events related to the specific endpoints it is written to handle:
@ProcessorBean(enabled=true, name=”com.company.extension.CustomProcessor”, immediate=true) public class CustomProcessor implements TrafficEventListener{
public void handleEvent(TrafficEvent event){
//write your custom code here
}
}
The annotation identifies the following properties:
TIBCO Mashery
®
Local Installation and Configuration Guide for Docker
30
●
●
●
enabled: Identifies if the processor is to be enabled.
name: Identifies the unique name of the processor as configured in API Settings (see marked area in ‘red’ in the following screenshot).
immediate: Identifies if the processor is enabled immediately.
The name used in the annotation for the Processor MUST be the same as configured on the portal for the Endpoint>Pre/Post Processing, as shown in the following screenshot:
Implementing Lifecycle Callback Handling
If you wish to have some initialization work done once and only once for each of the processors, then implement the following interface:
package com.mashery.trafficmanager.event.listener
:
/*** The lifecycle callback which gets called when the processor gets loaded when installed and released*/ public interface ListenerLifeCycle {
/*** The method is called once in the life-cycle of the processor before the processor is deemed ready to handle requests. If the processor throws an exception, the activation is assumed to be a failure and the processor will not receive any requests @throws ListenerLifeCycleException*/
public void onLoad(LifeCycleContext ctx) throws ListenerLifeCycleException;
/*** The method is called once in the life-cycle of the processor before the processor is removed due. The processor will not receive any requests upon inactivation.*/
public void onUnLoad(LifeCycleContext ctx);
}
The onLoad call is made once prior to the processor handling any requests and onUnLoad call is made before the processor is decommissioned and no more requests are routed to it.
The lifecycle listener can be implemented on the Processor class or on a separate class. The annotation needs to add a reference to the lifecycle-class if the interface is implemented (see highlighted property in bold).
package com.company.extension;
@ProcessorBean(enabled=true, name=”com.company.extension.CustomProcessor”, immediate=true, lifeCycleClass=”com.company.extension.CustomProcessor”)
public class CustomProcessor implements TrafficEventListener, ListenerLifeCycle{
public void handleEvent(TrafficEvent event){
//write your custom code here
}
public void onLoad(LifeCycleContext ctx) throws ListenerLifeCycleException{
TIBCO Mashery
®
Local Installation and Configuration Guide for Docker
31
}
public void onUnLoad(LifeCycleContext ctx){
}
}
The lifeCycleClass
property should point to the class implementing the Listener LifeCycle interface.
This also allows having a separate lifecycle listener interface as follows (note the different lifeCycleClass name).
The following example shows a different class implementing the LifeCycle callback: package com.company.extension;
@ProcessorBean(enabled=true, name=”com.company.extension.CustomProcessor”, immediate=true, lifeCycleClass=”com.company.extension.CustomProcessorLifeCycle”) public class CustomProcessor implements TrafficEventListener {
public void handleEvent(TrafficEvent event){
//write your custom code here
}
public void onLoad(LifeCycleContext ctx) throws ListenerLifeCycleException{
}
public void onUnLoad(LifeCycleContext ctx){
}
} public class CustomProcessorLifeCycle implements ListenerLifeCycle{
public void onLoad(LifeCycleContext ctx) throws ListenerLifeCycleException{
}
public void onUnLoad(LifeCycleContext ctx){
}
}
Adding Libraries to Classpath
If the processor needs third-party libraries, those can be used in development and packaged with the processors, as described in
Deploying Processors to Runtime .
Deploying Processors to Runtime
Deploying a custom processor involves the following general steps:
●
●
●
Packaging the custom processor
Uploading the custom processor
Enabling Debugging
The following sections describe these steps in more detail.
Packaging the Custom Processor
Once the processor code is written, compile the classes and create a jar file with all the classes. Any third party libraries used must be specified in the
Manifest.MF
of the jar containing the processor classes.
The classpath entries are introduced as follows. For example, if you want to add apache-commons.jar
, then you would add it as follows to the
META-INF/MANIFEST.MF
file of the jar:
Class-Path: apache-commons.jar
Uploading the Custom Processor
To upload the custom processor:
Procedure
● Once the jar file is created, add it to a .ZIP file. Upload the .ZIP file to the Mashery Local instance by using the Mashery Local Admin UI as shown:
TIBCO Mashery
®
Local Installation and Configuration Guide for Docker
32
If the upload is successful, a message appears that the adapters were uploaded successfully.
Enabling Debugging
During development, it is sometimes necessary to enable debugging on the Mashery Local instance.
To enable debugging, click the Enable debugging check box, indicate the port number to which you will connect your debugger, and then click Save:
TIBCO Mashery
®
Local Installation and Configuration Guide for Docker
Caching Content
The custom endpoints can cache content during the call handling. The cache configuration is found in the Manage Custom Content Cache section on the API Settings page.
33
Manage Custom Content Cache provides the following options:
●
●
●
●
Custom TTL: A default TTL provided for the cache.
Update TTL: Provides ability to save any TTL changes.
Update TTL & Flush Cache: Updates the database with the updated TTL and flushes the cache contents.
Flush Cache: Allows the cache contents to be flushed.
The SDK provides references to a Cache where all this data is stored. The cache interface provided in the callback to the
TrafficEventListener
is: package com.mashery.trafficmanager.cache;
/*** Cache API which allows extensions to store and retrieve data from cache*/ public interface Cache {
/**
* Retrieves the value from the cache for the given key
* @param key
* @return
* @throws CacheException
*/
Object get(String key) throws CacheException;
/**
* Puts the value against the key in the cache for a given ttl
* @param key
* @param value
* @param ttl
* @throws CacheException
*/
void put(String key, Object value, int ttl) throws CacheException;
}
A reference to the cache can be found on the
ProcessorEvent
which is reported on the callback. Here is an example of how to access cache on callback: package com.company.extension;
@ProcessorBean(enabled=true, name=”com.company.extension.CustomProcessor”, immediate=true public class CustomProcessor implements TrafficEventListener, ListenerLifeCycle{
public void handleEvent(TrafficEvent event){
ProcessorEvent processorEvent = (ProcessorEvent) event;
Cache cacheReference = processorEvent.getCache();
//Add data to cache
try{
TIBCO Mashery
®
Local Installation and Configuration Guide for Docker
cacheReference.put(“testkey”, “testValue”, 10)
}catch(CacheException e){
//load data or load default data
}
//write your custom processor code here
}
}
A reference to cache is also available on the lifecycle callback: package com.company.extension; public class CustomProcessorLifeCycle implements ListenerLifeCycle{
public void onLoad(LifeCycleContext ctx) throws ListenerLifeCycleException{
Cache cache = ctx.getCache();
// perform cache operations
}
public void onUnLoad(LifeCycleContext ctx){
}
}
34
TIBCO Mashery
®
Local Installation and Configuration Guide for Docker
