com.esri.arcgis.system
Class ObjectStream

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

All Implemented Interfaces:

com.esri.arcgis.interop.RemoteObjRef, IDocumentVersion, IObjectStream, ISequentialStream, IStream, Serializable

public class ObjectStream
extends Object
implements com.esri.arcgis.interop.RemoteObjRef, IObjectStream, IDocumentVersion

Specialized kind of IStream for objects.

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.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

See Also:

Serialized Form

Constructor Summary

ObjectStream()
Constructs a ObjectStream using ArcGIS Engine.

ObjectStream(Object obj)
Deprecated. As of ArcGIS 9.2, replaced by normal Java casts.
ObjectStream theObjectStream = (ObjectStream) obj;

Method Summary

void	commit(int grfCommitFlags) commit
boolean	equals(Object o) Compare this object with another
void	esri_clone(IStream[] ppstm) esri_clone
static String	getClsid() getClsid.
int	getDocumentVersion() The version of the document to save.
IStream	getStream() The aggregated stream object.
String	getVersion() The software version for the stream.
int	hashCode() the hashcode for this object
Object	loadObject(GUID riid, Object pUnkOuter) Load an object from the specified stream.
void	lockRegion(_ULARGE_INTEGER libOffset, _ULARGE_INTEGER cb, int dwLockType) lockRegion
void	remoteCopyTo(IStream pstm, _ULARGE_INTEGER cb, _ULARGE_INTEGER[] pcbRead, _ULARGE_INTEGER[] pcbWritten) remoteCopyTo
void	remoteRead(byte[] pv, int cb, int[] pcbRead) remoteRead
void	remoteSeek(_LARGE_INTEGER dlibMove, int dwOrigin, _ULARGE_INTEGER[] plibNewPosition) remoteSeek
void	remoteWrite(byte[] pv, int cb, int[] pcbWritten) remoteWrite
void	replaceObject(Object unknown) Replaces the current object with the object in the the specified stream.
void	revert() revert
void	saveObject(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) setSize
void	setStreamByRef(IStream ppStream) The aggregated stream object.
void	setVersion(String versionSpecifier) The software version for the stream.
void	stat(tagSTATSTG[] pstatstg, int grfStatFlag) stat
void	unlockRegion(_ULARGE_INTEGER libOffset, _ULARGE_INTEGER cb, int dwLockType) unlockRegion

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.esri.arcgis.interop.RemoteObjRef

getJintegraDispatch, release

Constructor Detail

ObjectStream

public ObjectStream()
             throws IOException,
                    UnknownHostException

Constructs a ObjectStream using ArcGIS Engine.

Throws:

IOException - if there are interop problems

UnknownHostException - if there are interop problems

ObjectStream

public ObjectStream(Object obj)
             throws IOException

Deprecated. As of ArcGIS 9.2, replaced by normal Java casts.
ObjectStream theObjectStream = (ObjectStream) obj;

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.

Parameters:

obj - an object returned from ArcGIS Engine or Server

Throws:

IOException - if there are interop problems

Method Detail

getClsid

public static String getClsid()

getClsid.

equals

public boolean equals(Object o)

Compare this object with another

Overrides:

equals in class Object

hashCode

public int hashCode()

the hashcode for this object

Overrides:

hashCode in class Object

setStreamByRef

public void setStreamByRef(IStream ppStream)
                    throws IOException,
                           AutomationException

The aggregated stream object.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

setStreamByRef in interface IObjectStream

Parameters:

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

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getStream

public IStream getStream()
                  throws IOException,
                         AutomationException

The aggregated stream object.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

getStream in interface IObjectStream

Returns:

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

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

saveObject

public void saveObject(Object pUnk)
                throws IOException,
                       AutomationException

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.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

saveObject in interface IObjectStream

Parameters:

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

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

loadObject

public Object loadObject(GUID riid,
                         Object pUnkOuter)
                  throws IOException,
                         AutomationException

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.

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.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

replaceObject

public void replaceObject(Object unknown)
                   throws IOException,
                          AutomationException

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

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

replaceObject in interface IObjectStream

Parameters:

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

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setVersion

public void setVersion(String versionSpecifier)
                throws IOException,
                       AutomationException

The software version for the stream.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

setVersion in interface IObjectStream

Parameters:

versionSpecifier - The versionSpecifier (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getVersion

public String getVersion()
                  throws IOException,
                         AutomationException

The software version for the stream.

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

getVersion in interface IObjectStream

Returns:

The versionSpecifier

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

remoteSeek

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

remoteSeek

Description

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

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setSize

public void setSize(_ULARGE_INTEGER libNewSize)
             throws IOException,
                    AutomationException

setSize

Description

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

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

setSize in interface IStream

Parameters:

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

Throws:

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 IOException,
                         AutomationException

remoteCopyTo

Description

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

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

commit

public void commit(int grfCommitFlags)
            throws IOException,
                   AutomationException

commit

Description

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

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

commit in interface IStream

Parameters:

grfCommitFlags - The grfCommitFlags (in)

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

revert

public void revert()
            throws IOException,
                   AutomationException

revert

Description

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

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

Specified by:

revert in interface IStream

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

lockRegion

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

lockRegion

Description

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

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

unlockRegion

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

unlockRegion

Description

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

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

stat

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

stat

Description

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

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

esri_clone

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

esri_clone

Product Availability

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

Specified by:

esri_clone in interface IStream

Parameters:

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

Throws:

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 IOException,
                       AutomationException

remoteRead

Description

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

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

remoteWrite

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

remoteWrite

Description

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

Product Availability

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

Supported Platforms

Windows, Solaris, Linux

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:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

setDocumentVersion

public void setDocumentVersion(int docVersion)
                        throws IOException,
                               AutomationException

The version of the document to save.

Product Availability

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

Specified by:

setDocumentVersion in interface IDocumentVersion

Parameters:

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

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.

getDocumentVersion

public int getDocumentVersion()
                       throws IOException,
                              AutomationException

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.

Product Availability

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

Specified by:

getDocumentVersion in interface IDocumentVersion

Returns:

A com.esri.arcgis.system.esriArcGISVersion constant

Throws:

IOException - If there are interop problems.

AutomationException - If the ArcObject component throws an exception.