Snapshot APIs
In this page we include information about the APIs that operate on Sim Trade Snapshots and Definitions. As in any part of the system, if you have a license for OpenComponents, use it, because it is so much easier to work with than OpenJVS.
A Quick Word on OpenComponents VS OpenJVS
OC is object-oriented, and more intuitive. It is easier to learn the API, which means that it is easier to on-board a developer to use the API. When a developer is engaged on a project, it is usually easier for them to communicate with a business analyst using a language that is closely aligned with the business requirements (easily understood by the BA) and the closely aligned with the API (easily understood by the TA). This is a generalization, but follow along some of the features here of OC and JVS and share in our conclusion about how much easier it is to work with OC.
Snapshot API: OpenComponents
OpenComponents supports taking an individual snapshot using transaction.saveSnapShot().
If a loaded Transaction is a snapshot, it may be deleted using transaction.deleteSnapshot(). An individual snapshot of a trade may also be deleted using tradingFactory.deleteSnapshot(int, int), passing in the tran_num and version_num.
You may retrieve a snapshot using the tradingFactory.retrieveSnapshot(int, int), passing in the tran_num and version_num.
OpenComponents has a TradeSnapshotDefinition class to retrieve existing definitions and to create new ones.
To create a new definition, pass in the name and transaction query to simulationFactory.createTradeSnapshotDefinition(String, Query). The transaction query will define the criteria of the trades to be snapped. The method will return the new snapshot definition. Use the .save() method to save the definition. The Query object can be loaded from the query name using tradingFactory.getQuery(String).
To load an existing snapshot definition, pass in the name of the definition to simulationFactory.retrieveTradeSnapshotDefinition(String).
Once you have created or loaded a snapshot definition, take the snapshot using tradeSnapshotDefinition.execute(TradeSnapshotType). This method returns the collection of trade snapshots as a TradeSnapshot object. TradeSnapshotType is static data that can be instantiated using staticDataFactory.getReferenceObject(EnumReferenceObject.TradeSnapshotType, String), where the String is the name, such as EOD.
You can also load a TradeSnapshot (which contains a set of Transactions) from simulationFactory.retrieveTradeSnapshot(TRadeSnapshotDefinition, TradeSnapshotType, Date). There are several methods available that accept different parameters.
From a TradeSnapshot, you can getTransactions() to retrieve the transactions in their required status as of that date.
From the TradeSnapshot, if you want to make a change to the transaction versions, add and remove transactions using addTransactions(..) and removeTransactions(..). There are several methods available that will allow you to pass in either a collection of Transactions or tran_num and tran_version_num parameters.
Overall, we find the API to be intuitive, once the basic concepts of snapshot definitions, sim trade snapshots, and transaction snapshots are well-understood.
private static void openComponentsSnapshotDemo(Session session) {
TradingFactory tf = session.getTradingFactory();
SimulationFactory sf = session.getSimulationFactory();
StaticDataFactory sdf = session.getStaticDataFactory();
//Load transaction, save individual snapshot, delete individual snapshot
Transaction transaction = tf.retrieveTransactionById(20001);
transaction.saveSnapShot();
transaction.deleteSnapshot();
//Create a new trade snapshot definition called [snapshotDefinitionName]
//that uses the query called [queryName]
String snapshotDefinitionName = "EOD MyPortfolio";
String queryName = "EOD MyPortfolio";
Query query = tf.getQuery(queryName);
TradeSnapshotDefinition tradeSnapshotDefinition = sf
.createTradeSnapshotDefinition(snapshotDefinitionName, query);
tradeSnapshotDefinition.save();
//Retrieve a snapshot definition called [snapshotDefinitionName]
//Take [EOD] snapshots
tradeSnapshotDefinition = sf
.retrieveTradeSnapshotDefinition(snapshotDefinitionName);
TradeSnapshotType tradeSnapshotType = (TradeSnapshotType) sdf
.getReferenceObject(EnumReferenceObject.TradeSnapshotType, "EOD");
TradeSnapshot tradeSnapshot = tradeSnapshotDefinition.execute(tradeSnapshotType);
//Retrieve previously-saved snapshots from the definition
//called [snapshotDefinitionName] with the type [EOD] for date [currentDate].
//Retrieve the snapshot's transactions.
Date currentDate= session.getMarket().getCurrentDate();
tradeSnapshot = sf.retrieveTradeSnapshot(
tradeSnapshotDefinition, tradeSnapshotType, currentDate);
tradeSnapshot.getTransactions();
} Snapshot API: OpenJVS
OpenJVS supports automatically taking an individual trade’s snapshot using transaction.saveTradeSnapshot(). Individual snapshots may be deleted using the static method Transaction.deleteTradeSnapshot(int, int), which takes tran_num and version_num.
You may retrieve a snapshot using the Transaction class’s static method Transaction.retrieveTradeSnapshot(int, int), passing in the tran_num and version_num.
OpenJVS has a SimTradeSnapshot class to retrieve existing definitions and create new ones. All methods on the class are static, and the javadocs are incomplete.
Create a new definition using SimTradeSnapshot.createDef(String, int) passing in the name of the new definition, and the query_id of a transaction query that defines which trades will be snapped.
Take a snapshot using the static method SimTradeSnapshot.create(int, int). There is no documentation on the method, but presumably the parameters should be the ID of the snapshot definition, and the ID of the snapshot type. Get the definition ID most easily using SimTradeSnapshot.getDefIdFromName(String).
Transactions can be added to or removed from a sim trade snapshot using an awkward pattern that requires creating an empty Table, filling the table via API, adding or removing trade details from the table, and passing the updated table as a parameter via API. We haven’t had to use this before, because we always favor OpenComponents. The documentation of these methods is spotty.
//Create an empty table
Table simTradeSnapshotTransactions = Table.tableNew("transactions");
//Fill the table with transaction details from the snapshot
SimTradeSnapshot.returnDetails(simTradeSnapshotId, 0, simTradeSnapshotTransactions);
//Add or remove transaction details from the table
updateTransactionDetails(simTradeSnapshotTransactions);
//Save the snapshot changes to the application
SimTradeSnapshot.addDetails(simTradeSnapshotId, simTradeSnapshotTransactions);