On this page:

Initializing an InputStream in JavaScript

The InputStream class provides a constructor that accepts up to three arguments. Legal argument values are:

• A communicator instance
• An encoding version
• A byte array containing the encoded data that you intend to decode

You'll normally supply the encoded data argument. The stream does not make a copy of this data; rather, it uses the data as supplied and assumes it remains unmodified for the lifetime of the stream object.

We recommend supplying a communicator instance, otherwise you will not be able to decode proxy objects. The stream also inspects the communicator's settings to configure several of its own default settings, but you can optionally configure these settings manually using methods that we'll describe later.

If you omit an encoding version, the stream uses the default encoding version of the communicator (if provided) or the most recent encoding version.

Use the following properties to manually configure the stream:

var stream = new Ice.InputStream(...);
stream.valueFactoryManager = ...
stream.logger = ...
stream.compactIdResolver = ...
stream.sliceValues = ...
stream.traceSlicing = ...

The settings include:

• Value factory manager
  A value factory manager supplies custom factories for Slice class types.

• Logger
  The stream uses a logger to record warning and trace messages.

• Compact ID resolver
  A compact ID resolver for translating numeric values into Slice type IDs. The stream invokes the resolver by passing it the numeric compact ID. The resolver is expected to return the Slice type ID associated with that numeric ID or an empty string if the numeric ID is unknown. The application must supply a function that accepts an integer and returns a string.

• Slice values
  The flag indicates whether to slice instances of Slice classes to a known Slice type when a more derived type is unknown. An instance is "sliced" when no static information is available for a Slice type ID and no factory can be found for that type, resulting in the creation of an instance of a less-derived type. If slicing is disabled in this situation, the stream raises the exception NoValueFactoryException. The default behavior is to allow slicing.

• Trace slicing
  The flag indicates whether to log messages when instances of Slice classes are sliced. If the stream is initialized with a communicator, this setting defaults to the value of the Ice.Trace.Slicing property, otherwise the setting defaults to false.

Extracting from an InputStream in JavaScript

InputStream provides a number of read methods that allow you to extract Slice types from the stream.

For example, you can extract a boolean and a string from a stream as follows:

var data = ...
var istr = new Ice.InputStream(communicator, data);
var b = istr.readBool();
var s = istr.readString();

Here are the methods for extracting data from a stream:

• readByte()
readBool()
readInt()
readLong()
readFloat()
readDouble()
readString()
  Extracts and returns a primitive value.

• readByteSeq()
  Extracts and returns a byte sequence as a "slice" of the internal buffer.

• readSize()
  The Ice encoding has a compact representation to indicate size. This function extracts a size and returns it as an integer.

• readAndCheckSeqSize(minWireSize)
  Like readSize, this function reads a size and returns it, but also verifies that there is enough data remaining in the unmarshaling buffer to successfully unmarshal the elements of the sequence. The minWireSize parameter indicates the smallest possible on-the-wire representation of a single sequence element. If the unmarshaling buffer contains insufficient data to unmarshal the sequence, the function throws UnmarshalOutOfBoundsException.

• readProxy(type)
  If no argument is provided, this function returns an instance of the base proxy type, ObjectPrx, otherwise it returns an instance of the given proxy type.

• readValue(cb, type)
  The Ice encoding for class instances requires extraction to occur in stages. The readValue function accepts a callback function that receives the extracted instance as its argument. The caller must also supply the class type expected for the instance. When the instance is available, the callback function is called. The application must call readPendingValues on the stream to ensure that all instances are properly extracted.

• readEnum(type)
  Extracts the integer value of an enumerator and returns the equivalent enumerator. The caller must pass the enumeration type as the argument.

• throwException()
  Extracts a user exception from the stream and throws it. If the stored exception is of an unknown type, the function attempts to extract and throw a less-derived exception. If that also fails, an exception is thrown: for the 1.0 encoding, the exception is UnmarshalOutOfBoundsException, for the 1.1 encoding, the exception is UnknownUserException.

• startSlice()
endSlice()
skipSlice()
  Start, end, and skip a slice of member data, respectively. These functions are used when manually extracting the slices of a class instance or user exception. The startSlice method returns the type ID of the next slice, which may be an empty string depending on the format used to encode the instance or exception.

• startValue()
endValue(preserve)
  The startValue method must be called prior to reading the slices of a class instance. The endValue method must be called after all slices have been read. Pass true to endValue in order to preserve the slices of any unknown more-derived types, or false to discard the slices. If preserve is true and the stream actually preserved any slices, the return value of endValue is a non-nil SlicedData object that encapsulates the slice data. If the caller later wishes to forward the instance with any preserved slices intact, it must supply this SlicedData object to the output stream.

• startException()
endException(preserve)
  The startException method must be called prior to reading the slices of an exception. The endException method must be called after all slices have been read. Pass true to endException in order to preserve the slices of any unknown more-derived types, or false to discard the slices. If preserve is true and the stream actually preserved any slices, the return value of endException is a non-nil SlicedData object that encapsulates the slice data. If the caller later wishes to forward the exception with any preserved slices intact, it must supply this SlicedData object to the output stream.

• startEncapsulation()
endEncapsulation()
skipEncapsulation()
  Start, end, and skip an encapsulation, respectively. The startEncapsulation and skipEncapsulation methods return the encoding version used to encode the contents of the encapsulation.

• skipEmptyEncapsulation(version)
  Skips an encapsulation that is expected to be empty. The stream raises EncapsulationException if the encapsulation is not empty. If the version argument is non-null, the stream stores the encoding version of the empty encapsulation in version.

• getEncapsulationSize()
  Returns the size of the current encapsulation.

• getEncoding()
  Returns the encoding version currently in use by the stream.

• readPendingValues()
  An application must call this function after all other data has been extracted, but only if class instances were encoded. This function extracts the state of class instances and invokes their corresponding callback functions (see readValue). For backward compatibility with encoding version 1.0, this function must only be called when non-optional data members or parameters use class types.

• readBlob(sz)
  Extracts an array of sz bytes from the stream at its current position. The returned byte array contains undecoded data from the stream's internal buffer. The stream's position is advanced by sz.

• skip(sz)
  Skips the given number of bytes.

• skipSize()
  Reads a size at the current position and skips that number of bytes.

• readOptional(tag, fmt)
  Returns true if an optional value with the given tag and format is present, or false otherwise. If this method returns true, the data associated with that optional value must be read next. Optional values must be read in order by tag from least to greatest. The OptionalFormat enumeration is equivalent to the following:

  Slice

  module Ice
  {
      enum OptionalFormat
      {
          OptionalFormatF1, OptionalFormatF2, OptionalFormatF4, OptionalFormatF8,
          OptionalFormatSize, OptionalFormatVSize, OptionalFormatFSize,
          OptionalFormatEndMarker
      }
  }

  Refer to the encoding discussion for more information on the meaning of these values.

• readOptionalHelper(tag, fmt, readFn)
If an optional value is present with the given tag and format, the stream invokes the given helper function to extract the value. For example, you can pass InputStream.prototype.readByte as the helper function when extracting an optional byte value. This function returns undefined if the optional value is not present.

• readOptionalProxy(tag, type)
If an optional value is present with the given tag and the correct format for a proxy, this function extracts the proxy information and returns a proxy instance of the given type, or ObjectPrx if no type is provided. This function returns undefined if the optional value is not present.

• readOptionalEnum(tag, type)
  If an optional value is present with the given tag and the correct format for the given enumeration type, this function extracts the enumerator and returns it. This function returns undefined if the optional value is not present.

• readOptionalValue(tag, cb, type)
  If an optional class instance is present with the given tag and the correct format for a class instance, this function begins the process of extracting the instance. The stream will invoke the callback function and pass it the instance as an argument. The caller must also supply the class type expected for the instance. The callback function receives the value undefined if the optional instance is not present.

Finally, you can use the pos property to get and set the stream's current position.

See Also

• Basic Data Encoding
• Data Encoding for Classes
• Data Encoding for Exceptions