Package com.caplin.datasource.interfaces

Interface DSRecord

All Superinterfaces:
DSData, DSPacket, DSSerializable, Iterable<DSField>
public interface DSRecord extends DSData

The interface that should be implemented by an instance of DSData of the type record. This interface extends DSData, and provides additional methods that allow the fields to be referenced and manipulated by name rather than by the field number.

  • Field Details

    • F_NOCACHE

      static final int F_NOCACHE
      Do not cache this update - pass directly through to clients. This flag only applies to type 1 record data.
      See Also:

    • DS_FIELDS_SEPARATOR

      static final int DS_FIELDS_SEPARATOR

      Field number that is used by DataSource to separate multiple updates within the same packet.

      See Also:

  • Method Details

    • getFieldByName

      DSField getFieldByName(String fieldName)

      Gets the first occurrence of the field with the specified field name.

      If there are three occurrences of the field Last, with values "75", "75.5" and "75.25", then calling getFieldByFieldName("Last") will return the field that contains the value "75".

      This is equivalent to calling getFieldByFieldName(fieldName, 0).

      Parameters:
      fieldName - The name of the field.
      Returns:
      The field for the first occurrence of the field name, or null if the specified field is not found.

    • getFieldByName

      DSField getFieldByName(String fieldName, int occurrence)

      Gets the specified occurrence of the field with the specified field name.

      If there are three occurrences of the field Last, with values "75", "75.5" and "75.25", then calling getFieldByFieldName("Last", 2) will return the field that contains the value "75.25".

      Parameters:
      fieldName - The name of the field.
      occurrence - The occurrence of the field to be got. The first field is occurrence 0, the next occurrence 1, and so on.
      Returns:
      The field for the specified occurrence of the field name, or null if the specified field is not found.

    • updateRecordData

      boolean updateRecordData(String fieldName, String value, int occurrence)

      Sets the value of the specified occurrence for a particular field name.

      If there are three occurrences of the field Last, "75", "75.5" and "75.25", then calling updateRecordData("Last", "76", 2) will change occurrences to be "75", "75.5" and "76".

      Parameters:
      fieldName - The name of the field.
      value - The new value for the field.
      occurrence - The occurrence of the field to be updated. The first field is occurrence 0, the next occurrence 1, and so on.
      Returns:
      true if the value was successfully set for the specified field, otherwise false.
      Throws:
      ArrayIndexOutOfBoundsException - ff there are fewer occurrences of the field than the specified occurrence to update.
      IllegalArgumentException - if the fieldName cannot be found in the FieldManager

    • updateRecordData

      boolean updateRecordData(String fieldName, String value)

      Sets the value of the first occurrence for the specified field name.

      If there are three occurrences of the field Last, "75", "75.5" and "75.25", then calling updateRecordData("Last", "76") will change occurrences to be "76", "75.5" and "75.25".

      This is equivalent to calling updateRecordData(fieldName, value, 0).

      Parameters:
      fieldName - The name of the field.
      value - The new value for the field.
      Returns:
      true if the value was successfully set for the specified field, otherwise false.
      Throws:
      IllegalArgumentException - if the fieldName cannot be found in the FieldManager

    • addRecordData

      void addRecordData(String fieldName, String value)

      Adds the String value for the specified field name.

      Parameters:
      fieldName - The name of the field.
      value - The value to be stored in the field.
      Throws:
      IllegalArgumentException - if the fieldName cannot be found in the FieldManager

    • addRecordData

      void addRecordData(String fieldName, char value)

      Adds the String representation of the character value for the specified field name.

      Parameters:
      fieldName - The name of the field.
      value - The value to be stored in the field.
      Throws:
      IllegalArgumentException - if the fieldName cannot be found in the FieldManager

    • addRecordData

      void addRecordData(String fieldName, char[] value)

      Adds the String representation of the character array for the specified field name.

      Parameters:
      fieldName - The name of the field.
      value - The value to be stored in the field.
      Throws:
      IllegalArgumentException - if the fieldName cannot be found in the FieldManager

    • addRecordData

      void addRecordData(String fieldName, double value)

      Adds the String representation of the double value for the specified field name.

      Warning: the underlying implementation will not guarantee any accuracy beyond 12 decimal places. If greater precision is required, the value should be formatted separately and added using the addRecordData(String, String) method.

      Parameters:
      fieldName - The name of the field.
      value - The value to be stored in the field.
      Throws:
      IllegalArgumentException - if the fieldName cannot be found in the FieldManager

    • addRecordData

      void addRecordData(String fieldName, float value)

      Adds the String representation of the float value for the specified field name.

      Warning: the underlying implementation will not guarantee any accuracy beyond 6 decimal places. If greater precision is required, the value should be formatted separately and added using the addRecordData(String, String) method.

      Parameters:
      fieldName - The name of the field.
      value - The value to be stored in the field.
      Throws:
      IllegalArgumentException - if the fieldName cannot be found in the FieldManager

    • addRecordData

      void addRecordData(String fieldName, int value)

      Adds the String representation of the integer value for the specified field name.

      Parameters:
      fieldName - The name of the field.
      value - The value to be stored in the field.
      Throws:
      IllegalArgumentException - if the fieldName cannot be found in the FieldManager

    • addRecordData

      void addRecordData(String fieldName, long value)

      Adds the String representation of the long value for the specified field name.

      Parameters:
      fieldName - The name of the field.
      value - The value to be stored in the field.
      Throws:
      IllegalArgumentException - if the fieldName cannot be found in the FieldManager

    • addBinaryRecordData

      void addBinaryRecordData(String fieldName, byte value)

      Adds the byte value for the specified field name. This method Base64 encodes the value before storing it.

      Parameters:
      fieldName - The name of the field.
      value - The byte value to be stored in the field.
      Throws:
      IllegalArgumentException - if the fieldName cannot be found in the FieldManager

    • addBinaryRecordData

      void addBinaryRecordData(String fieldName, short value)

      Adds the short value for the specified field name. This method Base64 encodes the value before storing it.

      Parameters:
      fieldName - The name of the field.
      value - The value to be stored in the field.
      Throws:
      IllegalArgumentException - if the fieldName cannot be found in the FieldManager

    • addBinaryRecordData

      void addBinaryRecordData(String fieldName, int value)

      Adds the integer value for the specified field name. This method Base64 encodes the value before storing it.

      Parameters:
      fieldName - The name of the field.
      value - The value to be stored in the field.
      Throws:
      IllegalArgumentException - if the fieldName cannot be found in the FieldManager

    • addBinaryRecordData

      void addBinaryRecordData(String fieldName, long value)

      Adds the long value for the specified field name. This method Base64 encodes the value before storing it.

      Parameters:
      fieldName - The name of the field.
      value - The value to be stored in the field.
      Throws:
      IllegalArgumentException - if the fieldName cannot be found in the FieldManager

    • addBinaryRecordData

      void addBinaryRecordData(String fieldName, float value)

      Adds the float value for the specified field name. This method Base64 encodes the value before storing it.

      Parameters:
      fieldName - The name of the field.
      value - The value to be stored in the field.
      Throws:
      IllegalArgumentException - if the fieldName cannot be found in the FieldManager

    • addBinaryRecordData

      void addBinaryRecordData(String fieldName, double value)

      Adds the double value for the specified field name. This method Base64 encodes the value before storing it.

      Parameters:
      fieldName - The name of the field.
      value - The value to be stored in the field.
      Throws:
      IllegalArgumentException - if the fieldName cannot be found in the FieldManager

    • addBinaryRecordData

      void addBinaryRecordData(String fieldName, byte[] value)

      Adds the byte array value for the specified field name. This method Base64 encodes the value before storing it.

      Parameters:
      fieldName - The name of the field.
      value - The array of bytes to be stored in the field.
      Throws:
      IllegalArgumentException - if the fieldName cannot be found in the FieldManager

    • addBinaryRecordData

      void addBinaryRecordData(String fieldName, String value)

      Adds the String value for the specified field name. This method Base64 encodes the value before storing it.

      Parameters:
      fieldName - The name of the field.
      value - The value to be stored in the field.
      Throws:
      IllegalArgumentException - if the fieldName cannot be found in the FieldManager

    • addDataSeparator

      void addDataSeparator()

      Adds a separator field, with field number DS_FIELDS_SEPARATOR, to the DSRecord, allowing multiple type 2 and type 3 record entries to be contributed in a single update. Please see the examples below for how this works.

      Multiple type 2 entries contribution example

      In this example, field "MktMkrId" is the type 2 index, whilst "Bid" is a type 2 price field. This example will send two type 2 entries, one for Caplin (with a Bid of 100) and one for Another Marker Maker (with a Bid of 102.5).

      Note: The type 2 index field must be the first field in an update or after a separator field. 

       DSRecord type2Record;
 // ... some code to create the record
 type2Record.addRecordData("MktMkrId", "Caplin");
 type2Record.addRecordData("Bid", 100.0);
 type2Record.addDataSeparator();
 type2Record.addRecordData("MktMkrId", "Another Market Maker");
 type2Record.addRecordData("Bid", 102.5);
 type2Record.send();

      Multiple type 3 entries contribution example

      This example will send the values 205, 210, 212.5 and 215 for the Last field, with the last one (215) interpreted as the most recent. 

       DSRecord type3Record;
 // ... some code to create the record
 type3Record.addRecordData("Last", 205.0);
 type3Record.addDataSeparator();
 type3Record.addRecordData("Last", 210.0);
 type3Record.addDataSeparator();
 type3Record.addRecordData("Last", 212.5);
 type3Record.addDataSeparator();
 type3Record.addRecordData("Last", 215.0);
 type3Record.send();