Package org.marketcetera.strategy

Marketcetera Strategies.

See: Description

Interface Summary

Interface	Description
Messages	Message keys for the strategy module.
RunningStrategy	An interface to a running strategy that facilitates communication to the strategy.
Strategy	A Strategy object to be executed.
StrategyMXBean	MXBean interface for Strategies.

Class Summary

Class	Description
AbstractRunningStrategy	Base class for running strategies.
CompilationFailed.Diagnostic	Diagnostic information provided by the compiler for a compilation error or warning.
JavaClasspathExecutionEngine	Executes a Java strategy using the default classpath.
JavaCompilerExecutionEngine	Executes a Java strategy using the Java Compiler API.
StrategyModuleConfig	Provides configuration for the StrategyModule.
StrategyModuleFactory	Strategy Agent module factory implementation for the strategy module.

Enum Summary

Enum	Description
CompilationFailed.Type	Indicates what type of diagnostic was returned from the compiler.
Language	Defines the set of strategy languages available.
OutputType	Describes the types of data that a strategy can emit.
Status	Indicates the status of a running strategy.

Exception Summary

Exception	Description
CompilationFailed	Indicates that a strategy could not be compiled.
StrategyException	An exception thrown during execution of a Strategy.

Package org.marketcetera.strategy Description

Marketcetera Strategies.

Overview

Supported Languages

• Java
  Java strategy support is provided by a Java 6 JSR-199 compliant Java compiler.
• Ruby
  Ruby strategy support is provided by JRuby 1.1.3.

Strategy Structure

Overview

Class Structure

A strategy consists of any block of executable code in the given language. The strategy may consist of one or more classes specified in a single file. These classes may refer to each other, Marketcetera classes, or external classes stored in a jar file. To be executable by the Marketcetera platform, however, one of the classes in the strategy file must be a language-appropriate subclass of the Marketcetera Strategy class as follows:

• Java - org.marketcetera.strategy.java.Strategy
• Ruby - org.marketcetera.strategy.ruby.Strategy

The code to be executed is contained in a local file. The basename of the file must comply with the rules of the corresponding compiler for that strategy's language implementation. The implementation of the strategy itself and its supporting classes and external references, if any, are likewise constrained by the strategy language.

API

A strategy has access to tools and data from the Marketcetera platform. This set of information and tools is collectively referred to as the strategy API. The syntax for the API varies by language, but the function is the same.

Data

Data refers to the set of strategy methods that are called by the Marketcetera platform. To receive data, override one or more of the following methods in the primary class of the strategy.

onStart

                void onStart()
                on_start
            

Called when the strategy starts. This is a good place to establish data flows with requestMarketData, requestCEPData, or requestProcessedMarketData. Data requests initiated during onStart may cause data to be delivered before onStart completes.

onStop

                void onStop()
                on_stop
            

Called when the strategy stops. Any cleanup that the strategy needs to do may be done here. It is not necessary to cancel initiated data flows as all data requests made by a strategy are automatically canceled. It is not permitted to make new data requests, send or cancel orders, or send suggestions in onStop.

onAsk

                void onAsk(org.marketcetera.event.AskEvent)
                on_ask(ask)
            

Called when the strategy receives an ask event. Ask events are received if the strategy has submitted a market data or complex event processing request.

onBid

                void onBid(org.marketcetera.event.BidEvent)
                on_bid(bid)
            

Called when the strategy receives a bid event. Bid events are received if the strategy has submitted a market data or complex event processing request.

onTrade

                void onTrade(org.marketcetera.event.TradeEvent)
                on_trade(trade)
            

Called when the strategy receives a trade event. Trade events are received if the strategy has submitted a market data or complex event processing request.

onMarketstat

                void onMarketstat(org.marketcetera.event.MarketstatEvent)
                on_marketstat(marketstat)
            

Called when the strategy receives a marketstat event. Marketstat events are received if the strategy has submitted a market data or complex event processing request.

onDividend

                void onDividend(org.marketcetera.event.DividendEvent)
                on_dividend(dividend)
            

Called when the strategy receives a dividend event. Dividend events are received if the strategy has submitted a market data or complex event processing request.

onCancelReject

                void onCancelReject(org.marketcetera.trade.OrderCancelReject)
                on_cancel_reject(cancel)
            

Called when the strategy receives an order cancel reject event. Order cancel reject events are received if the strategy is connected to the Marketcetera server. Note that the strategy will received order cancel reject events for all rejected orders, not just the orders the strategy created.

onExecutionReport

                void onExecutionReport(org.marketcetera.trade.ExecutionReport)
                on_execution_report(execution_report)
            

Called when the strategy receives an execution report. Execution report events are received if the strategy is connected to the Marketcetera server. Note that the strategy will received execution report events for all orders, not just the orders the strategy created.

onCallback

                void onCallback(java.lang.Object)
                on_callback(data)
            

Called when the strategy receives a scheduled callback from Marketcetera as requested by the strategy via requestCallbackAfter(long,java.lang.Object) or requestCallbackAt(long,java.lang.Object). The object returned is the same object that is passed to the request.

onOther

                void onOther(java.lang.Object)
                on_other(data)
            

Called when the strategy receives an object that does not fall into any of the above categories

Services

Services refers to the set of methods a strategy may execute that provide data.

getParameter

                java.lang.String getParameter(java.lang.String)
                get_parameter(key)
            

Retrieves the parameter specified by the given key or null/nil if no such parameter exists. Parameters are specified to the strategy at start time as a map of key/value pairs. The parameters specified are private to the given strategy.

getProperty

                java.lang.String getProperty(java.lang.String)
                get_property(key)
            

Retrieves the property specified by the given key or null/nil if no such property exists. Unlike getParameter, properties are common to all running strategies in the same Marketcetera process. Changes made by one strategy will be visible to all other strategies.

getExecutionReports

                org.marketcetera.trade.ExecutionReport[] getExecutionReports(org.marketcetera.trade.OrderID)
                get_execution_reports(orderID)
            

Retrieves the execution reports that correspond to the given order. The order must have been sent by this strategy during this strategy session. In order to receive execution reports, the strategy must be connected to the Marketcetera server. The values returned may not correspond to the aggregate set of execution reports supplied via onExecutionReport as getExecutionReports is limited to execution reports from orders sent by this strategy and onExecutionReport receives all execution reports.

getBrokers

                org.marketcetera.client.brokers.BrokerStatus[] getBrokers()
                get_brokers
            

Retrieves the brokers known to the Marketcetera server. The strategy must be connected to the Marketcetera server to retrieve brokers.

getPositionAsOf

                java.math.BigDecimal getPositionAsOf(java.util.Date,java.lang.String)
                get_position_as_of(date,symbol)
            

Retrieves the most accurate position of the given symbol at the given point of time possible. The position may be temporarily inaccurate if there are ongoing changes in the position of the given symbol. The strategy must be connected to the Marketcetera server to retrieve positions. If the position cannot be retrieved, this method will return null/nil. If there is no current position in the given symbol at the given time, this method will return 0.

getURN

                org.marketcetera.module.ModuleURN getURN()
                get_urn()
            

Retrieves the ModuleURN of the strategy

Actions

Actions refers to the set of methods a strategy may execute each of which effects a specific change.

setProperty

                void setProperty(java.lang.String,java.lang.String)
                set_property(key,value)
            

Sets the given key to the given value, creating the given key if it does exist, otherwise overwriting the existing value. All strategies share properties in common, so one strategy may change data another strategy created.

requestCallbackAfter

                void requestCallbackAfter(long,java.lang.Object)
                request_callback_after(delay,data)
            

Requests a callback from the Marketcetera platform after the given delay in milliseconds has elapsed. The Marketcetera platform will execute onCallback, passing it the given object.

requestCallbackAt

                void requestCallbackAt(long,java.lang.Object)
                request_callback_at(time,data)
            

Requests a callback from the Marketcetera platform at the given time, specified in milliseconds since epoch. The Marketcetera platform will execute onCallback, passing it the given object.

requestMarketData

                int requestMarketData(java.lang.String,java.lang.String)
                request_market_data(symbols,source)
            

Requests full depth-of-book market data from the given market data source for the given symbol or symbols. Symbols is a comma-separated list of symbols specified in the format appropriate for the given market data source. The data will be delivered as incremental updates via onBid, onAsk, and onTrade. The market data will continue to arrive until the request is canceled via cancelDataRequest(int) or cancelAllDataRequests(). This method returns an identifier that refers to this market data request. The identifier can be used to cancel the market data request. If the request fails, the method returns 0.

cancelDataRequest

                void cancelDataRequest(int)
                cancel_data_request(id)
            

Cancels the data request associated with the given id. If the id does not correspond to an active data request created by this strategy in this session, this method does nothing. This method may be used to cancel either a market data or complex event processor request.

cancelAllDataRequests

                void cancelAllDataRequests()
                cancel_all_data_requests()
            

Cancels all active data (both market data and complex event processor) requests created by this strategy in this session.

requestCEPData

                int requestCEPData(java.lang.String[],java.lang.String)
                request_cep_data(statements,source)
            

Requests data from the given complex event processor source for the query specified by the given statements. Statements is an array of strings specified in the format appropriate for the given complex event processor source. The data will be delivered as incremental updates via the appropriate data method. The complex event processor data will continue to arrive until the request is canceled via cancelDataRequest(int) or cancelAllDataRequests(). This method returns an identifier that refers to this complex event processor request. The identifier can be used to cancel the complex event processor request. If the request fails, the method returns 0.

requestProcessedMarketData

                int requestProcessedMarketData(java.lang.String,java.lang.String,java.lang.String[],java.lang.String)
                request_processed_market_data(symbols,marketDataSource,statments,cepSource)
            

Requests market data specified by the given comma-separated list of symbols from the given market data source processed by the given complex event processor query executed in the given complex event processor source. The format of the arguments is identical to that of the union of requestMarketData and requestCEPData. The data will be delivered as incremental updates via the appropriate data method. The data will continue to arrive until the request is canceled via cancelDataRequest(int) or cancelAllRequests(). This method returns an identifier that refers to this request. The identifier can be used to cancel the request. If the request fails, the method returns 0.

suggestTrade

                void suggestTrade(org.marketcetera.trade.OrderSingle,java.math.BigDecimal,java.lang.String)
                suggest_trade(order,score,identifier)
            

Suggests a trade for the given order with the given confidence score and identifying label. Trade suggestions are sent by the strategy to the destination specified for trade suggestions when the strategy is created. The order should have sufficient information to prevent it from being rejected; no validation is done when a trade suggestion is created. There is no way to cancel a trade suggestion nor can a trade suggestion that is converted to an order be canceled by the strategy that created the suggestion. It is recommended that the score for a trade suggestion fall in the interval [0.0,1.0]. The identifier can be any value desired.

send

                java.lang.boolean send(java.lang.Object)
                send(data)
            

Sends an object to the destination specified when the strategy is created. The value returned indicates whether the object was successfully transmitted or not.

cancelOrder

                org.marketcetera.trade.OrderCancel cancelOrder(org.marketcetera.trade.OrderID,java.lang.boolean)
                cancel_order(orderID,inSendOrder)
            

Sends a request to cancel the given order. The order must have been created by this strategy during this strategy session. The cancel request will be sent to the same destination specified for orders. The OrderCancel is returned. It is submitted if inSendOrder is true, otherwise it is the caller's responsibility to submit the order manually with sendOther. Note that successful execution of this method does not guarantee that an order will be canceled, just that the cancel request was sent.

cancelReplace

                org.marketcetera.trade.OrderReplace cancelReplace(org.marketcetera.trade.OrderID,org.marketcetera.trade.OrderSingle,java.lang.boolean)
                cancel_replace(orderID,newOrder,sendOrder?)
            

Sends a request to cancel and replace the order represented by the given OrderID with the given new order. The original order must have been created by this strategy during this strategy session. The cancel replace request will be sent to the same destination specified for orders. The OrderReplace returned can be used to cancel the order or collect execution reports for it. Note that successful execution of this method does not guarantee that an order will be canceled and replaced, just that the cancel and replace request was sent. If submitOrder is false, the order will be returned but not submitted. It is the caller's responsibility to submit the order manually. This would be done, for example, if the user needed to customize the CancelOrder before it is submitted.

cancelAllOrders

                int cancelAllOrders()
                cancel_all_orders()
            

Sends requests to cancel all orders created by by this strategy during this strategy session. The cancel requests will be sent to the same destination specified for orders. The return value indicates how many cancel requests were successfully sent. Note that successful execution of this method does not guarantee that an order will be canceled, just that the cancel requests were sent.

sendMessage

                void sendMessage(quickfix.MessageMessage,org.marketcetera.trade.BrokerID)
                send_message(fixMessage,broker)
            

Sends the given FIX message routed to the given broker. The FIX message will be sent to the same location specified for orders. The broker may be chosen from the list returned by getBrokers(). This method is intended to be used in special cases when sendOrder is not adequate.

sendEventToCEP

                void sendEventToCEP(org.marketcetera.event.EventBase,java.lang.String)
                send_event_to_cep(event,source)
            

Sends the given event to the specified CEP source. The default query namespace for the strategy is the target within the given CEP source.

sendEvent

                void sendEvent(org.marketcetera.event.EventBase)
                send_event(event)
            

Sends the given event to the event subscribers for this strategy. Each strategy may have a number of subscribers that express interest in events published by it. This method will send the given event to those subscribers.

notifyLow

                void notifyLow(java.lang.String,java.lang.String)
                notify_low(subject,body)
            

Transmits a low priority notification with the given subject and body. The notifications are emitted to the strategy output stream.

notifyMedium

                void notifyMedium(java.lang.String,java.lang.String)
                notify_medium(subject,body)
            

Transmits a medium priority notification with the given subject and body. The notifications are emitted to the strategy output stream.

notifyHigh

                void notifyHigh(java.lang.String,java.lang.String)
                notify_high(subject,body)
            

Transmits a high priority notification with the given subject and body. The notifications are emitted to the strategy output stream.

debug

                void debug(java.lang.String)
                debug(message)
            

Emits the given message to the strategy log stream. This message will be emitted only if the appropriate logger category is activated for the strategy module.

info

                void info(java.lang.String)
                info(message)
            

Emits the given message to the strategy log stream. This message will be emitted only if the appropriate logger category is activated for the strategy module.

warn

                void warn(java.lang.String)
                warn(message)
            

Emits the given message to the strategy log stream. This message will be emitted only if the appropriate logger category is activated for the strategy module.

error

                void error(java.lang.String)
                error(message)
            

Emits the given message to the strategy log stream. This message will be emitted only if the appropriate logger category is activated for the strategy module.

createDataFlow

                org.marketcetera.module.DataFlowID createDataFlow(java.lang.boolean,org.marketcetera.module.DataRequest...)
                create_data_flow(appendToDataSink?,requests)
            

Creates a data flow between modules as described by the given DataRequest objects. Appends data to the data sink if so indicated. Normal rules apply with respect to modules being available for data flows. The DataFlowID returned may be used to cancel the data flow. When the strategy ends, all data flows are automatically halted.

cancelDataFlow

                void cancelDataFlow(org.marketcetera.module.DataFlowID)
                cancel_data_flow(dataFlowID)
            

Cancels the data flow with the given DataFlowID.

Strategy Operation

Parameters

Strategies may be given a map of string-based key/value pairs at creation time. These values are private to the given strategy instance and are accessible via getParameter(java.lang.String). The parameter values are immutable while the strategy is running. No other strategies may see a strategy's parameters. Properties are created external to the strategy and passed in.

Properties

Strategies have acces to an additional map of string-based key/value pairs called properties. These values are common to all running strategy instances and are accessible via getProperty(java.lang.String) and setProperty(java.lang.String,java.lang.String).

Destinations

When a strategy is created, destinations may be specified for orders and suggestions. All suggestions created by the strategy are routed to the suggestion destination. All orders, FIX messages, cancels, and cancel/replaces are routed to the orders destination. If the orders or suggestion destination is not specified, then the corresponding category of data will not be sent.

Module Framework Interface

Strategies can be run from within Strategy Agent - the container of our module framework. To run a strategy, create it then start it:

                createModule;metc:strategy:system;metc:strategy:system:<instancename>,<classname>,<languagename>,<filepath>,,,metc:sink:system
                startModule;metc:strategy:system:<instancename>
        

where:

• <instancename> is the user-specified name of the strategy. The name must be unique among all running strategies
• <languagename> is the name of the language in which the strategy is implemented. This value must match the name of a supported language
• <classname> is the name of the primary class implemented in the strategy file. This class must extend the appropriate Strategy class in a language-appropriate fashion.
• <filepath> is the location of the strategy script file.

The last parameter, metc:sink:system, is the destination for all strategy emissions. The sink destination is a catch-all data repository that allows the data to be created by the strategy and captured, but makes sure that the orders and suggestions do not get routed to a broker. Note that if the strategy executes market data requests, the corresponding market data provider must be started before the request is made. To stop the strategy, execute:

                stopModule;metc:strategy:system:<instancename>
        

See Strategy Agent documentation for more details on commands file syntax.

Technical Information

Since:

2.0.0

Version:

$Id$

Author:

Colin DuPlantis