DataSource XML configuration schema

This page describes the schema of the deprecated DataSource XML configuration file.

XML configuration files were deprecated in DataSource 6.2, and removed in DataSource 7. For information on the modern configuration syntax, see DataSource configuration reference: introduction.

Overview

Elements

<dataSource>

The root tag for configuring a DataSource.

Configures how peers will identify and connect to this DataSource application. This application will identify its peers using the information set in the <peer> tags.

If SSL is enabled keystores must be correctly configured. See https://docs.oracle.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html#CreateKeystore for further details.

Attributes
Name	Type	Default	Required	Description
appName	string	[class name]	No	The name of this DataSource, and how DataSource peers will identify it. This name can be overridden by putting a value in the name attribute of a <peer> element.
id	int	0	No	ID number of this DataSource. This ID can be overridden by putting a value in the id attribute of a <peer> element. It must match the id attribute given in the <remote> element of the remote DataSource’s configuration
address	string	localhost1	No	Network interface to listen for connections from DataSource peers
port	int	0	No	Network port to listen for connections from DataSource peers. The default of 0 means that no connections can be made to this DataSource
SSLAddress	string	localhost	No	Network interface to listen for SSL connections from DataSource peers
SSLPort	int	0	No	Network port to listen for SSL connections from DataSource peers. The default of 0 means that no SSL connections can be made to this DataSource
peerConnectionTimeout	int	10	No	The amount of time to wait for a valid peer info packet (protocol negotiation) when making or receiving a peer connection.

Example

<dataSource xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" port="25099" appName="TEST">
  <logging count="7" level="CONFIG"/>
  <packetLog cycleTime="60" cyclePeriod="60" count="168" />
  <peer>
    <local id="112" type="ACTIVE CONTRIB"/>
    <destination address="merlin" port="25007" />
  </peer>
</dataSource>

<logging>

Configures how your DataSource application logs internal status messages and error messages.

This tag will result in a java.util.logging.Logger instance being created with the specified configuration. This logger instance is available from com.caplin.datasource.DataSource.getLogger().

Please note that from version 6.0 configuring your logger in XML is not recommended. The preferred approach is to pass your java.util.logging.Logger into the factory method com.caplin.datasource.DataSourceFactory.createDataSource(String, String, Logger). If you use this factory method then you must remove any logging configuration from your XML configuration file, otherwise an IllegalStateException will be thrown.

The logging element is deprecated from version 6.0.

Attributes
Name	Type	Default	Required	Description
cyclePeriod	int	1440	No	The time in minutes between log file rotations. The default and maximum value is one day (1440 minutes).
cycleTime	int	240	No	If cyclePeriod is one day then cycleTime is the time in minutes from midnight for the first log file rotation. If cyclePeriod is less than one day then cycleTime is a time period in minutes, used to split up the day starting from midnight, the first log file rotation will occur at the start of the next period. Example 1: if cycleTime is 15 the first log file rotation will occur the next time it is 0, 15, 30 or 45 minutes past an hour. Example 2: if cycleTime is 120 the first log file rotation will occur at the start of the next even hour. The default value is 240 which, with the default cyclePeriod of 1440, means the logs are cycled at 4:00am every day.
maxSize	long	0	No	The maximum size in bytes of the log before rotating, or 0 for no limit. If maxSize is not zero cyclePeriod and cycleTime will be ignored.
count	int	10	No	Specifies how many wrapped logs to keep, including the currently used log. If this attribute is left out then 10 logs files will be maintained.
rotateLogOnStartup	boolean	false	No	Whether the datasource rotates the existing log file on startup rather than appending to it.
subsystem	string	com.caplin.datasrc.DataSource	No	The name for the Logger (see java.util.logging.Logger). If DataSources have the same logger name, in the same process, they will use the same logger. If DataSource have diffrent logger names they use different loggers and will log to diffrent files.
default	boolean	true	No	Specifies whether the default DataSource implementation of java.util.logging.Handler is used publishing log messages. The default handler writes to a text file. Each line writes out the date in ISO8601 format, the level of the message and the message itself.
level	string	INFO	No	Sets the java.util.logging.Level for DataSource logging. This will pick up any custom levels that have been added as well as the standard levels. The standard Java levels for logging messages are: OFF SEVERE WARNING INFO CONFIG FINE FINER FINEST ALL The logger will inherit the system default of any logging properties.
useParentHandlers	boolean	false	No	Specifies whether or not this logger should send its output to its parent Logger.

Example

<logging level="CONFIG" cycleTime="120" cyclePeriod="120" count="84" />

<packetLog>

Configures how your DataSource records binary messages sent between this DataSource and its peers.

This tag will result in a packet-level log file being created with the specified configuration, unless the noPacketLog attribute is set.

Attributes
Name	Type	Default	Required	Description
cyclePeriod	int	1440	No	The time in minutes between log file rotations. The default and maximum value is one day (1440 minutes).
cycleTime	int	240	No	If cyclePeriod is one day then cycleTime is the time in minutes from midnight for the first log file rotation. If cyclePeriod is less than one day then cycleTime is a time period in minutes, used to split up the day starting from midnight, the first log file rotation will occur at the start of the next period. Example 1: if cycleTime is 15 the first log file rotation will occur the next time it is 0, 15, 30 or 45 minutes past an hour. Example 2: if cycleTime is 120 the first log file rotation will occur at the start of the next even hour. The default value is 240 which, with the default cyclePeriod of 1440, means the logs are cycled at 4:00am every day.
maxSize	long	0	No	The maximum size in bytes of the log before rotating, or 0 for no limit. If maxSize is not zero cyclePeriod and cycleTime will be ignored.
count	int	10	No	Specifies how many wrapped logs to keep, including the currently used log. If this attribute is left out then 10 logs files will be maintained.
rotateLogOnStartup	boolean	false	No	Whether the datasource rotates the existing log file on startup rather than appending to it.
noPacketLog	boolean	false	No	If true, suppresses writing out a packet log.

Example

<packetLog cycleTime="30" cyclePeriod="30" count="336" />

<pattern>

Pattern tag is optional and there can be only one in a <packetLog> or <logging> tag. It allows to specify the name of the initial log to be created by the DataSource (rotated log files will have a .number appended to this). The pattern may be constructed with an expression for java.text.SimpleDateFormat class to parse, so the file names would contain the actual date and/or time.

There are several special character allowed:

%t - java.io.tempdir property
%u - user.home property
%h - hostname
%r - current directory
%n or %a - application name (the name of the main() class)

Attributes
Name	Type	Default	Required	Description
patternType	string	text	No	Possible values: "text" - patternString parameter contains a string to name the log file with, "date" - patternString parameter contains date pattern for the java.text.SimpleDateFormat class.
patternString	string	packet.log	No	Contains the pattern to name the log file. With patternType="date" it should be in java.text.SimpleDateFormat acceptable format.

Example

<packetLog cycleTime="30" cyclePeriod="30" count="336" />
   <pattern patternType="date" patternString="'%u/packet-%n-'yyyy-MM-dd'.log'" />
</packetLog>

<latencyChainManger>

Tag for enabling latency chaining.

Attributes
Name	Type	Default	Required	Description
InitialTimeStampField	string	LTY_INIT_TS	No	Field name for the InitialTimeStamp. This fields contains the start time of the chain in milliseconds.
TimeStampListField	string	LTY_LIST_TS	No	Field name for the TimeStampList. This fields contains a comma separated list of time deltas.
EventListField	string	LTY_LIST_EVENT	No	Field name for the EventLis. This fields contains a comma separated list of events corresponding to the time deltas.
Base64	string	ignore	No	Sets the configuration for Base64 encoding of the fields. ignore - no Base64 encoding detect - inspect received fields to see if they are using Base64 encoding and decode if it is encoded decode - decode all received latency chain fields encode - encode all transmitted fields with Base64

Example

<latencyChainManager
  InitialTimeStampField="LTY_INIT_TS"
  TimeStampListField="LTY_LIST_TS"
  EventListField="LTY_LIST_EVENT"/>

<peer>

Parent tag containing the elements which configure how this application communicates with its peers. Multiple destinations should be used to enable failover. If multiple destinations are present then connections to the destinations will be attempted in the order the tags appear in the XML.

Attributes
Name	Type	Default	Required	Description
ssl	boolean	false	No	f true, uses the Secure Sockets Layer (SSL) protocol when connecting to another peer. Note: if SSL is enabled keystores must be correctly configured. See https://docs.oracle.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html#CreateKeystore for further details.
msgQueueSize	int	200	No	Sets the size of the message queue that will buffer outgoing messages in the event of the peer disconnect and then send them when the peer connection is re-established.
ejectExistingConnection	boolean	true	No	Whether this peer (if listening for inbound connections) should eject any existing connection when a new peer connection is received.
enableTCPNoDelay	boolean	false	No	Set whether the peer socket should use TCP_NODELAY. This setting should be true if the lowest possible message latency is required. When set to true, there is a trade-off of maximum throughput (messages / second) that will be possible.

Example

<peer>
  <local id="112" name="CaplinTest" type="ACTIVE CONTRIB"/>
  <destination address="merlin" port="25007" />
  <destination address="merlin2" port="25005" />
</peer>

<heartbeat>

Configures the rate of heartbeats sent between peers which indicate the health of connections. This heartbeat rate is just a suggestion: on connection to a peer, the DataSources will negotiate a suitable heartbeat rate. If the peer doesn’t support heartbeats then they will not be sent.

Attributes
Name	Type	Default	Required	Description
time	long	-1	No	The time, in milliseconds, between heartbeats. The default (-1) means heartbeats are turned off. A suggested time is 15000 as this will send a heartbeat every 15 seconds if no other traffic is being sent, which is suitable for most firewall configurations.
slackTime	long	5000	No	The delay, in milliseconds, after the time attribute before the peer connection is terminated and your application attempts to reconnect due to no heartbeat being received.

Example

<heartbeat time="5000" slackTime="2000" />

<local>

Configures the type information that the DataSource sends to this peer to identify its capabilities.

Attributes
Name	Type	Required	Description
name	string	No	Name of this DataSource. Overrides the `appName` attribute of the `<dataSource>` tag.
id	int	No	ID number of this DataSource. Overrides the `id` attribute of the `<dataSource>` tag.
type	string	No	Type of this DataSource. Possible values are shown below and can be either one or both, space separated. This type information is used by the peer so that it knows what operations this DataSource provides. Without either values the peer assumes this DataSource to be a Broadcast source that doesn’t support Contributions. ACTIVE: This application only sends updates to those peers which requested them) CONTRIB: This application will receive contributions made by clients to objects which it supplies updates for).

Example

<local id="112" name="CaplinTest" type="ACTIVE CONTRIB"/>

<remote>

Configures the expected capabilites of this peer. Note: once connected, this peer may send different capabilities, which will override those set here.

Attributes
Name	Type	Default	Required	Description
name	string	src_index of peer	No	Name of DataSource peer. Will be overridden by the peer once the connection is established.
id	int	0	No	ID number of the DataSource peer that will connect.
type	string		No	Type of this DataSource. Possible values are shown below and can be either one or both, space separated. This type information is used by the DataSource so that it knows what operations this peer is expected to provide. This may differ from the actual operations that the peer provides, these will be set at connection time. Without either values this DataSource assumes the peer to be a Broadcast source that doesn’t support Contributions. ACTIVE: This peer operates in active mode. Can be overridden by the peer once the connection is established. CONTRIB: This peer can receive contributions made by clients to objects which it supplies updates for.

Example

<remote id="115" name="CaplinOther" type="ACTIVE"/>

<destination>

Configures the location of this peer.

Attributes
Name	Type	Default	Required	Description
address	string	localhost	No	The address to connect to
port	int	25000	No	The port to connect to.

Example

<destination address="merlin" port="25007" />

<jmxManager>

Tag containing the elements which configure jmx monitoring for this application.

Attributes
Name	Type	Default	Required	Description
enable	boolean	false	No	Specifies whether JMX monitoring is enabled or not.
root	string	javadatasrc	No	Specifies the prefix which will be applied to all MBeans created by this datasource, except the ServerType MBean which has no prefix.
serverType	string	javadatasrc	No	Specifies the type of application this is, which clients can use to determine what MBeans this datasource will provide. For a Java dataSource this should nearly always be javadatasrc, however if you have provided custom Views for you Enterprise Management Console that can distinguish between specialist types of Java DataSource then you should use the dataSource’s distinguishing serverType string here instead.
rmiRegistryPort	integer	1099	No	Specifies the port on which the RMI registry into which the MBeanServer is bound will listen; this is the port that tools (such as the Enterprise Management Console) will generally connect to.
rmiClientPort	integer	-1	No	Specifies the port on which the RMI registry will provide a connection to the MBeanServer. Note: the default value of -1 will cause java to allocate an arbitrary available port when required. This may cause problems if you need to connect via JMX through a firewall, so it is recommended that this attribute is specified explicitly.
hostInterface	string	See description	No	Specifies the network interface on which to export RMI servers and also causes RMI stubs to be embedded with that network interface’s IP address. If not set the default Java RMI behaviour of listening on all network interfaces and embedding the primary interface’s IP address into the stub occurs.

Example

<jmxManager enable="true" rmiRegistryPort="4567" hostInterface="192.168.35.100" root="production-source-1"/>

<sendDirect>

Tag containing the attribute which configures the default com.caplin.datasrc.DSSendManager (a com.caplin.datasrc.SendDirect instance for this DataSource). If a SendDirect instance is not used, this tag has no effect.

Attributes
Name	Type	Default	Required	Description
sendMessagesToDisconnectedPeers	boolean	true	No	Specifies whether or not the SendDirect instance should attempt to send messages to Peers that are currently disconnected. If true all messages are sent to all Peers otherwise, if false, messages are only sent to Peers that are currently connected. If a message is sent to a disconnected peer it may be buffered in the Peer’s outgoing message queue and subsequently may still be delivered to the message consumer. Not sending messages to disconnected peers improves performance, particularly if there are high numbers of disconnected peers.

Example

<sendDirect sendMessagesToDisconnectedPeers="true" />

<udpSignal>

Attributes
Name	Type	Default	Required	Description
address	string		No
port	int		Yes

<replayManager>

Attributes
Name	Type	Required
replayType	string	No
dateString	string	No
dateFormatClass	string	No
fileName	string	No
symbol	string	No
fieldNum	int	No
fieldVal	string	No

<delayManager>

Attributes
Name	Type	Required
blockRealTime	boolean	No
batchTime	long	No
batchSize	int	No

<delayChannel>

Attributes
Name	Type	Required
prefix	string	No
delayTime	long	No
batchTime	long	No
batchSize	int	No

<messagingManager>

Attributes
Name	Type	Default	Required	Description
messageType	string		No

<namespace>

Attributes
Name	Type	Default	Required	Description
pattern	string		No
ackPrefix	string		No

<messagingFields>

Attributes
Name	Type	Default	Required	Description
classname	string		No

<users>

Attributes
Name	Type	Default	Required	Description
classname	string		No

<user>

Attributes
Name	Type	Required
username	string	No
password	string	No
classname	string	No