RTI Connext Java API  Version 5.0.0
AbstractPrimitiveSequence Class Referenceabstract
Inheritance diagram for AbstractPrimitiveSequence:
AbstractSequence Sequence Copyable Sequence BooleanSeq ByteSeq CharSeq DoubleSeq FloatSeq IntSeq LongSeq ShortSeq

Public Member Functions

final Class getElementType ()
 
void loan (Object buffer, int new_length)
 Loan a contiguous buffer to this sequence.
 
void unloan ()
 Return the loaned buffer in the sequence and set the maximum to 0.
 
final boolean hasOwnership ()
 Return the value of the owned flag.
 
final void clear ()
 
final void setSize (int newSize)
 
final int size ()
 
final Object copy_from (Object src)
 
- Public Member Functions inherited from AbstractSequence
void add (int index, Object element)
 Inserts the specified element at the specified position in this sequence.
 
boolean add (Object element)
 Appends the specified element to the end of this sequence.
 
final Object remove (int index)
 Remove the element at the given index by shifting all subsequent elements "left" by one.
 
- Public Member Functions inherited from Sequence
int getMaximum ()
 Get the current maximum number of elements that can be stored in this sequence.
 
void setMaximum (int new_max)
 Resize this sequence to a new desired maximum.
 
Class getElementType ()
 

Detailed Description

A base class for sequences whose elements are of primitive types. Such sequences do not support null values.

Member Function Documentation

final Class getElementType ( )
Returns
the primitive type of this sequence, not the wrapper type.
See Also
com.rti.dds.util.Sequence::getElementType()
void loan ( Object  buffer,
int  new_length 
)

Loan a contiguous buffer to this sequence.

This operation changes the owned flag of the sequence to com.rti.dds.infrastructure.false and also sets the underlying buffer used by the sequence. See the User's Manual for more information about sequences and memory ownership.

Use this method if you want to manage the memory used by the sequence yourself. You must provide an array of elements and integers indicating how many elements are allocated in that array (i.e. the maximum) and how many elements are valid (i.e. the length). The sequence will subsequently use the memory you provide and will not permit it to be freed by a call to com.rti.dds.infrastructure.com.rti.dds.util.Sequence.Sequence.setMaximum.

By default, a sequence you create owns its memory unless you explicitly loan memory of your own to it. In a very few cases, RTI Connext will return a sequence to you that has a loan; those cases are documented as such. For example, if you call com.rti.ndds.example.FooDataReader.read or com.rti.ndds.example.FooDataReader.take and pass in sequences with no loan and no memory allocated, RTI Connext will loan memory to your sequences which must be unloaned with com.rti.ndds.example.FooDataReader.return_loan. See the documentation of those methods for more information.

Precondition
com.rti.dds.infrastructure.com.rti.dds.util.Sequence.Sequence.getMaximum == 0; i.e. the sequence has no memory allocated to it.
com.rti.dds.infrastructure.com.rti.dds.util.Sequence.AbstractPrimitiveSequence.hasOwnership == com.rti.dds.infrastructure.true; i.e. the sequence does not already have an outstanding loan
Postcondition
The sequence will store its elements in the buffer provided.
com.rti.dds.infrastructure.com.rti.dds.util.Sequence.AbstractPrimitiveSequence.hasOwnership == com.rti.dds.infrastructure.false
com.rti.dds.infrastructure.com.rti.dds.util.Sequence.Sequence.size() == new_length
com.rti.dds.infrastructure.com.rti.dds.util.Sequence.Sequence.getMaximum == new_max
Parameters
bufferThe new buffer that the sequence will use. Must point to enough memory to hold new_max elements of type Foo. It may be NULL if new_max == 0.
new_lengthThe desired new length for the sequence.
Returns
com.rti.dds.infrastructure.true if buffer is successfully loaned to this sequence or com.rti.dds.infrastructure.false otherwise. Failure only occurs due to failing to meet the pre-conditions. Upon failure the sequence remains unmodified.
See Also
com.rti.dds.infrastructure.com.rti.dds.util.Sequence.unloan, com.rti.dds.infrastructure.com.rti.dds.util.Sequence.loan_discontiguous
void unloan ( )

Return the loaned buffer in the sequence and set the maximum to 0.

This method affects only the state of this sequence; it does not change the contents of the buffer in any way.

Only the user who originally loaned a buffer should return that loan, as the user may have dependencies on that memory known only to them. Unloaning someone else's buffer may cause unspecified problems. For example, suppose a sequence is loaning memory from a custom memory pool. A user of the sequence likely has no way to release the memory back into the pool, so unloaning the sequence buffer would result in a resource leak. If the user were to then re-loan a different buffer, the original creator of the sequence would have no way to discover, when freeing the sequence, that the loan no longer referred to its own memory and would thus not free the user's memory properly, exacerbating the situation and leading to undefined behavior.

Precondition
owned == com.rti.dds.infrastructure.false
Postcondition
owned == com.rti.dds.infrastructure.true
maximum == 0
Returns
com.rti.dds.infrastructure.true if the preconditions were met. Otherwise com.rti.dds.infrastructure.false. The function only fails if the pre-conditions are not met, in which case it leaves the sequence unmodified.
See Also
com.rti.dds.infrastructure.com.rti.dds.util.Sequence.AbstractPrimitiveSequence.loan(Object, int), com.rti.dds.infrastructure.com.rti.dds.util.Sequence.loan_discontiguous, com.rti.dds.infrastructure.com.rti.dds.util.Sequence.Sequence.setMaximum
final boolean hasOwnership ( )

Return the value of the owned flag.

Returns
com.rti.dds.infrastructure.true if sequence owns the underlying buffer, or com.rti.dds.infrastructure.false if it has an outstanding loan.
final void clear ( )

Set the logical size of this sequence to zero. This method does not generate any garbage for collection.

See Also
java.util.Collection::clear()
final void setSize ( int  newSize)

Set the logical size of this sequence to the given value.

Parameters
newSizethe new logical size of this sequence; it must be less than or equal to the maximum allocated length of the underlying array.
Exceptions
IndexOutOfBoundsExceptionif the new size is less than zero or greater than the allocated length of the array.
See Also
AbstractSequence::getMaximum()
final int size ( )

The logical size of this sequence.

final Object copy_from ( Object  src)

Implementation of the Copyable interface.

Parameters
srcAn AbstractPrimitiveSequence which contains the data to be copied.
Returns
this
Exceptions
NullPointerExceptionIf src is null.
ClassCastExceptionIf src is not a Sequence OR if one of the objects contained in the Sequence is not of the expected type.

RTI Connext Java API Version 5.0.0 Copyright © Thu Aug 30 2012 Real-Time Innovations, Inc