com.esri.arcgis.system
Class ObjectStream

java.lang.Object
  com.esri.arcgis.system.ObjectStream

All Implemented Interfaces:

IDocumentVersion, IObjectStream, ISequentialStream, IStream, java.io.Serializable

public class ObjectStream

extends java.lang.Object

implements IObjectStream, IDocumentVersion

Specialized kind of IStream for objects.

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Supported Platforms

Windows, Solaris, Linux

Description

When implementing your own objects, you will sometimes need to provide support for persistence. For example, with a custom feature renderer, persistence enables its settings to be written to an MXD file so that when ArcMap is restarted, the layer having custom rendering will be drawn in the same way as previously drawn. The COM concept of streams provides a way of reading and writing data to the persisted storage.

The ObjectStream is designed to allow you to correctly persist collections of ArcObjects objects in which there may be multiple references to a single object. For example if you persist both a Map and a LegendItem to the same stream, both may have references to a single layer. The ObjectStream ensures that the layer is only written to the persistence stream once. If you persist objects without an ObjectStream, you run the risk that the objects will be incorrectly rehydrated.

See the topics on implementing persistence for more details on implementing persistence on your custom objects with IObjectStream.

See Also:

Serialized Form

Constructor Summary

ObjectStream()
Constructs a ObjectStream using ArcGIS Engine.

ObjectStream(java.lang.Object obj)
Deprecated. As of ArcGIS 9.2, replaced by normal Java casts.

Method Summary

void	commit(int grfCommitFlags) Supported Platforms
boolean	equals(java.lang.Object o) Compare this object with another
void	esri_clone(IStream[] ppstm)
IDocumentVersion	getAsIDocumentVersion() Deprecated. No replacement. The object reference can be directly used where the implemented interface is needed.
IObjectStream	getAsIObjectStream() Deprecated. No replacement. The object reference can be directly used where the implemented interface is needed.
static java.lang.String	getClsid()
int	getDocumentVersion() The version of the document to save.
IStream	getStream() The aggregated stream object.
java.lang.String	getVersion() The software version for the stream.
int	hashCode() the hashcode for this object
java.lang.Object	loadObject(GUID riid, java.lang.Object pUnkOuter) Load an object from the specified stream.
void	lockRegion(_ULARGE_INTEGER libOffset, _ULARGE_INTEGER cb, int dwLockType) Supported Platforms
void	remoteCopyTo(IStream pstm, _ULARGE_INTEGER cb, _ULARGE_INTEGER[] pcbRead, _ULARGE_INTEGER[] pcbWritten) Supported Platforms
void	remoteRead(byte[] pv, int cb, int[] pcbRead) Supported Platforms
void	remoteSeek(_LARGE_INTEGER dlibMove, int dwOrigin, _ULARGE_INTEGER[] plibNewPosition) Supported Platforms
void	remoteWrite(byte[] pv, int cb, int[] pcbWritten) Supported Platforms
void	replaceObject(java.lang.Object unknown) Replaces the current object with the object in the the specified stream.
void	revert() Supported Platforms
void	saveObject(java.lang.Object pUnk) Store an object to the specified stream.
void	setDocumentVersion(int docVersion) The version of the document to save.
void	setSize(_ULARGE_INTEGER libNewSize)
void	setStreamByRef(IStream ppStream) The aggregated stream object.
void	setVersion(java.lang.String versionSpecifier) The software version for the stream.
void	stat(tagSTATSTG[] pstatstg, int grfStatFlag) Supported Platforms
void	unlockRegion(_ULARGE_INTEGER libOffset, _ULARGE_INTEGER cb, int dwLockType) Supported Platforms

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ObjectStream

public ObjectStream()
             throws java.io.IOException,
                    java.net.UnknownHostException

Constructs a ObjectStream using ArcGIS Engine.

Throws:

java.io.IOException - if there are interop problems

java.net.UnknownHostException - if there are interop problems

ObjectStream

public ObjectStream(java.lang.Object obj)
             throws java.io.IOException

Deprecated. As of ArcGIS 9.2, replaced by normal Java casts.

Construct a ObjectStream using a reference to such an object returned from ArcGIS Engine or Server. This is semantically equivalent to casting obj to ObjectStream.
ObjectStream theObjectStream = (ObjectStream) obj;

Parameters:

obj - an object returned from ArcGIS Engine or Server

Throws:

java.io.IOException - if there are interop problems

Method Detail

getClsid

public static java.lang.String getClsid()

getAsIObjectStream

public IObjectStream getAsIObjectStream()

Deprecated. No replacement. The object reference can be directly used where the implemented interface is needed.

getAsIDocumentVersion

public IDocumentVersion getAsIDocumentVersion()

Deprecated. No replacement. The object reference can be directly used where the implemented interface is needed.

equals

public boolean equals(java.lang.Object o)

Compare this object with another

hashCode

public int hashCode()

the hashcode for this object

setStreamByRef

public void setStreamByRef(IStream ppStream)
                    throws java.io.IOException,
                           AutomationException

Description copied from interface: IObjectStream

The aggregated stream object.

Specified by:

setStreamByRef in interface IObjectStream

Parameters:

ppStream - A reference to a com.esri.arcgis.system.IStream (in)

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

getStream

public IStream getStream()
                  throws java.io.IOException,
                         AutomationException

Description copied from interface: IObjectStream

The aggregated stream object.

Supported Platforms

Windows, Solaris, Linux

Specified by:

getStream in interface IObjectStream

Returns:

A reference to a com.esri.arcgis.system.IStream

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

saveObject

public void saveObject(java.lang.Object pUnk)
                throws java.io.IOException,
                       AutomationException

Description copied from interface: IObjectStream

Store an object to the specified stream. The first time the object is stored, the full object is written to the stream. When the object is subsequently stored, a reference is stored.

Supported Platforms

Windows, Solaris, Linux

Specified by:

saveObject in interface IObjectStream

Parameters:

pUnk - A reference to another Object (IUnknown) (in)

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

loadObject

public java.lang.Object loadObject(GUID riid,
                                   java.lang.Object pUnkOuter)
                            throws java.io.IOException,
                                   AutomationException

Description copied from interface: IObjectStream

Load an object from the specified stream. The first time an object is encountered, it is loaded from the stream. When subsequent references to the object are loaded, a pointer to the first object is returned.

Supported Platforms

Windows, Solaris, Linux

Remarks

The first parameter of LoadObject is a GUID of an interface ID (most of them could be find under HKEY_CLASSES_ROOT/Interface in the registry), not the object's GUID. The object that gets loaded will QI for this interface and the result is returned with the IUnknown parameter.

Specified by:

loadObject in interface IObjectStream

Parameters:

riid - A Structure: com.esri.arcgis.support.ms.stdole.GUID (in)

pUnkOuter - A reference to another Object (IUnknown) (in)

Returns:

A reference to another Object (IUnknown)

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

replaceObject

public void replaceObject(java.lang.Object unknown)
                   throws java.io.IOException,
                          AutomationException

Description copied from interface: IObjectStream

Replaces the current object with the object in the the specified stream.

Supported Platforms

Windows, Solaris, Linux

Specified by:

replaceObject in interface IObjectStream

Parameters:

unknown - A reference to another Object (IUnknown) (in)

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

setVersion

public void setVersion(java.lang.String versionSpecifier)
                throws java.io.IOException,
                       AutomationException

Description copied from interface: IObjectStream

The software version for the stream.

Supported Platforms

Windows, Solaris, Linux

Specified by:

setVersion in interface IObjectStream

Parameters:

versionSpecifier - The versionSpecifier (in)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getVersion

public java.lang.String getVersion()
                            throws java.io.IOException,
                                   AutomationException

Description copied from interface: IObjectStream

The software version for the stream.

Supported Platforms

Windows, Solaris, Linux

Specified by:

getVersion in interface IObjectStream

Returns:

The versionSpecifier

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

remoteSeek

public void remoteSeek(_LARGE_INTEGER dlibMove,
                       int dwOrigin,
                       _ULARGE_INTEGER[] plibNewPosition)
                throws java.io.IOException,
                       AutomationException

Description copied from interface: IStream

Supported Platforms

Windows, Solaris, Linux

Description

IStream is a Microsoft interface. Please refer to MSDN for information about this interface.

Specified by:

remoteSeek in interface IStream

Parameters:

dlibMove - A Structure: com.esri.arcgis.system._LARGE_INTEGER (in)

dwOrigin - The dwOrigin (in)

plibNewPosition - A Structure: com.esri.arcgis.system._ULARGE_INTEGER (out: use single element array)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setSize

public void setSize(_ULARGE_INTEGER libNewSize)
             throws java.io.IOException,
                    AutomationException

Specified by:

setSize in interface IStream

Parameters:

libNewSize - A Structure: com.esri.arcgis.system._ULARGE_INTEGER (in)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

remoteCopyTo

public void remoteCopyTo(IStream pstm,
                         _ULARGE_INTEGER cb,
                         _ULARGE_INTEGER[] pcbRead,
                         _ULARGE_INTEGER[] pcbWritten)
                  throws java.io.IOException,
                         AutomationException

Description copied from interface: IStream

Supported Platforms

Windows, Solaris, Linux

Description

IStream is a Microsoft interface. Please refer to MSDN for information about this interface.

Specified by:

remoteCopyTo in interface IStream

Parameters:

pstm - A reference to a com.esri.arcgis.system.IStream (in)

cb - A Structure: com.esri.arcgis.system._ULARGE_INTEGER (in)

pcbRead - A Structure: com.esri.arcgis.system._ULARGE_INTEGER (out: use single element array)

pcbWritten - A Structure: com.esri.arcgis.system._ULARGE_INTEGER (out: use single element array)

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

commit

public void commit(int grfCommitFlags)
            throws java.io.IOException,
                   AutomationException

Description copied from interface: IStream

Supported Platforms

Windows, Solaris, Linux

Description

IStream is a Microsoft interface. Please refer to MSDN for information about this interface.

Specified by:

commit in interface IStream

Parameters:

grfCommitFlags - The grfCommitFlags (in)

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

revert

public void revert()
            throws java.io.IOException,
                   AutomationException

Description copied from interface: IStream

Supported Platforms

Windows, Solaris, Linux

Description

IStream is a Microsoft interface. Please refer to MSDN for information about this interface.

Specified by:

revert in interface IStream

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

lockRegion

public void lockRegion(_ULARGE_INTEGER libOffset,
                       _ULARGE_INTEGER cb,
                       int dwLockType)
                throws java.io.IOException,
                       AutomationException

Description copied from interface: IStream

Supported Platforms

Windows, Solaris, Linux

Description

IStream is a Microsoft interface. Please refer to MSDN for information about this interface.

Specified by:

lockRegion in interface IStream

Parameters:

libOffset - A Structure: com.esri.arcgis.system._ULARGE_INTEGER (in)

cb - A Structure: com.esri.arcgis.system._ULARGE_INTEGER (in)

dwLockType - The dwLockType (in)

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

unlockRegion

public void unlockRegion(_ULARGE_INTEGER libOffset,
                         _ULARGE_INTEGER cb,
                         int dwLockType)
                  throws java.io.IOException,
                         AutomationException

Description copied from interface: IStream

Supported Platforms

Windows, Solaris, Linux

Description

IStream is a Microsoft interface. Please refer to MSDN for information about this interface.

Specified by:

unlockRegion in interface IStream

Parameters:

libOffset - A Structure: com.esri.arcgis.system._ULARGE_INTEGER (in)

cb - A Structure: com.esri.arcgis.system._ULARGE_INTEGER (in)

dwLockType - The dwLockType (in)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

stat

public void stat(tagSTATSTG[] pstatstg,
                 int grfStatFlag)
          throws java.io.IOException,
                 AutomationException

Description copied from interface: IStream

Supported Platforms

Windows, Solaris, Linux

Description

IStream is a Microsoft interface. Please refer to MSDN for information about this interface.

Specified by:

stat in interface IStream

Parameters:

pstatstg - A Structure: com.esri.arcgis.system.tagSTATSTG (out: use single element array)

grfStatFlag - The grfStatFlag (in)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

esri_clone

public void esri_clone(IStream[] ppstm)
                throws java.io.IOException,
                       AutomationException

Specified by:

esri_clone in interface IStream

Parameters:

ppstm - A reference to a com.esri.arcgis.system.IStream (out: use single element array)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

remoteRead

public void remoteRead(byte[] pv,
                       int cb,
                       int[] pcbRead)
                throws java.io.IOException,
                       AutomationException

Description copied from interface: ISequentialStream

Supported Platforms

Windows, Solaris, Linux

Description

ISequentialStream is a Microsoft interface. Please refer to MSDN for information about this interface.

Specified by:

remoteRead in interface ISequentialStream

Parameters:

pv - An unsigned byte (out: use single element array)

cb - The cb (in)

pcbRead - The pcbRead (out: use single element array)

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

remoteWrite

public void remoteWrite(byte[] pv,
                        int cb,
                        int[] pcbWritten)
                 throws java.io.IOException,
                        AutomationException

Description copied from interface: ISequentialStream

Supported Platforms

Windows, Solaris, Linux

Description

ISequentialStream is a Microsoft interface. Please refer to MSDN for information about this interface.

Specified by:

remoteWrite in interface ISequentialStream

Parameters:

pv - An unsigned byte (in)

cb - The cb (in)

pcbWritten - The pcbWritten (out: use single element array)

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.

setDocumentVersion

public void setDocumentVersion(int docVersion)
                        throws java.io.IOException,
                               AutomationException

Description copied from interface: IDocumentVersion

The version of the document to save.

Specified by:

setDocumentVersion in interface IDocumentVersion

Parameters:

docVersion - A com.esri.arcgis.system.esriArcGISVersion constant (in)

Throws:

java.io.IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getDocumentVersion

public int getDocumentVersion()
                       throws java.io.IOException,
                              AutomationException

Description copied from interface: IDocumentVersion

The version of the document to save.

Remarks

Determines which version an object is persisted. This can be useful when saving an object ObjectStream or MemoryBlobStream and you want the version of that object to be compatible with previous releases of ArcGIS. Not all persistable objects implement IDocumentVersion; you should ensure the object supports this interface before accessing this property.

Specified by:

getDocumentVersion in interface IDocumentVersion

Returns:

A com.esri.arcgis.system.esriArcGISVersion constant

Throws:

AutomationException - If the ArcObject component throws an exception.

java.io.IOException - If there are interop problems.