com.thomsonreuters.ema.access.OmmArray Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of ema Show documentation
Show all versions of ema Show documentation
Enterprise Message API (EMA) Java Edition
///*|-----------------------------------------------------------------------------
// *| This source code is provided under the Apache 2.0 license --
// *| and is provided AS IS with no warranty or guarantee of fit for purpose. --
// *| See the project's LICENSE.md for details. --
// *| Copyright Thomson Reuters 2015. All rights reserved. --
///*|-----------------------------------------------------------------------------
package com.thomsonreuters.ema.access;
import java.util.Collection;
/**
* OmmArray is a homogeneous container of primitive data type entries.
*
* OmmArray is a collection which provides iterator over the elements in this
* collection.
*
* The following code snippet shows additions to OmmArray.
*
* OmmArray array = EmaFactory.createOmmArray();
* array.fixedWidth(2);
* array.add(EmaFactory.createOmmArrayEntry().intValue(22));
* array.add(EmaFactory.createOmmArrayEntry().intValue(25));
*
*
* The following code snippet shows extracting data from OmmArray.
*
* for(OmmArrayEntry arrayEntry : array)
* {
* System.out.print(" DataType: " + DataType.asString(arrayEntry.load().dataType()) + " Value: ");
*
* if(Data.DataCode.BLANK == arrayEntry.code())
* System.out.println(" blank");
* else
* switch (arrayEntry.loadType())
* {
* case DataTypes.REAL:
* System.out.println(arrayEntry.real().asDouble());
* break;
* case DataTypes.DATE:
* System.out.println(arrayEntry.date().day() + " / " + arrayEntry.date().month() + " / "
* + arrayEntry.date().year());
* break;
* case DataTypes.TIME:
* System.out.println(arrayEntry.time().hour() + ":" + arrayEntry.time().minute() + ":"
* + arrayEntry.time().second() + ":" + arrayEntry.time().millisecond());
* break;
* case DataTypes.INT:
* System.out.println(arrayEntry.intValue());
* break;
*
* ...
* }
* }
*
*
* Objects of this class are intended to be short lived or rather transitional.
* This class is designed to efficiently perform setting and extracting of OmmArray and its content.
* Objects of this class are not cache-able.
*
* @see Data
* @see OmmArrayEntry
* @see OmmReal
* @see OmmState
* @see OmmQos
*/
public interface OmmArray extends Data, Collection
{
/**
* Indicates presence of FixedWidth.
*
* @return true if fixed width is set; false otherwise
*/
public boolean hasFixedWidth();
/**
* Returns FixedWidth.
*
* @return fixed width
*/
public int fixedWidth();
/**
* Clears the OmmArray. Invoking clear() method clears all the values and
* resets all the defaults.
*/
public void clear();
/**
* Specifies FixedWidth. Setting fixed-width implies each array entry has
* been populated with the same fixed size, to allow minimizing bandwidth.
* Setting fixed-width as 0 implies the data contained in the array entries
* may be of different sizes, to allow the flexibility of different sized
* encoding;
*
* When using a fixed width, the application still passes in the base
* primitive type when encoding (e.g., if encoding fixed width
* DataTypes.INT types, an Int is passed in regardless of itemLength).
* When encoding buffer types as fixed width: Any content that exceeds
* fixedWidth will be truncated Any content that is shorter than fixedWidth
* will be padded with the \0 (NULL) character.
*
* Only specific types are allowed as fixed-width encodings. Here lists supported fixed widths and allowable data ranges:
*
* DataType::IntEnum supports one byte(-2^7 to 2^7-1), two byte(-2^15 to 2^15-1), four byte((-2^31 to 2^31-1), or eight byte((-2^63 to 2^63-1).
* DataType::UIntEnum supports one byte(0 to 2^8-1), two byte(0 to 2^16-1), four byte(0 to 2^32-1), or eight byte(0 to 2^64-1).
* DataType::FloatEnum supports four byte, floating point type that represents the same range of values allowed by the system float type. Follows the IEEE 754 specification.
* DataType::DoubleEnum supports eight byte, floating point type that represents the same range of values allowed by the system double type. Follows the IEEE 754 specification.
* DataType::DateEnum supports four byte(year, month, day).
* DataType::TimeEnum supports:
* three byte(hour, minute, second);
* five byte(hour, minute, second, millisec);
* seven byte(hour, minute, second, millisec, microsec);
* eight byte(hour, minute, second, millisec, microsec, nanosec).
* DataType::DateTimeEnum supports:
* seven byte(year, month, day, hour, minute, second);
* nine byte(year, month, day, hour, minute, second, millisec);
* eleven byte(year, month, day, hour, minute, second, millisec, microsec);
* twelve byte(year, month, day, hour, minute, second, millisec, microsec, nanosec);
* DataType::EnumEnum supports one byte(0 to 2^8-1) or two byte(0 to 2^16-1).
* DataType::BufferEnum, DataType::AsciiEnum, DataType::Utf8Enum, and
* DataType::RmtesEnum support any legal width value.
*
*
* @throws OmmInvalidUsageException
* if an entry was already added
*
* @param width
* specifies fixed width value
* @return reference to this object
*/
public OmmArray fixedWidth(int width);
}