eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'DataStream':

Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: DataStream


Inheritance:

   Object
   |
   +--Stream
      |
      +--PeekableStream
         |
         +--PositionableStream
            |
            +--WriteStream
               |
               +--ReadWriteStream
                  |
                  +--RWBinaryOrTextStream
                     |
                     +--DataStream
                        |
                        +--ReferenceStream

Package:
stx:libcompat
Category:
Compatibility-Squeak
Version:
rev: 1.19 date: 2018/05/15 16:09:03
user: cg
file: DataStream.st directory: libcompat
module: stx stc-classLibrary: libcompat

Description:


DO NOT DIRECTLY REFER TO THIS CLASS OR USE IT OTHERWISE IN YOUR CODE:

compatibility class for squeak compatible object loading support.
DataStreams are Squeak's equivalent of the Binary Object Storage mechanism;
they marshall/demarshall objects onto/from a stream.

This does not support recursive object references (i.e. cycles).
For that, Squeak uses a ReferenceStream.

This is required e.g. by monticello.
However, only the minimum functionality as required by monticello is supported
here. Do not use it for your own binary storage / persistance,
unless you intent to exchange data with squeak/pharo applications.


Class protocol:

cleanup
o  cleanUp
Re-initialize DataStream to avoid hanging onto obsolete classes

initialization
o  initializeTypeMaps
TypeMap maps Smalltalk classes to type ID numbers which identify the data stream primitive formats. nextPut: writes these IDs to the data stream. NOTE: Changing these type ID numbers will invalidate all extant data stream files. Adding new ones is OK.
Classes named here have special formats in the file. If such a class has a subclass, it will use type 9 and write correctly. It will just be slow. (Later write the class name in the special format, then subclasses can use the type also.)
See nextPut:, next, typeIDFor:, & ReferenceStream>>isAReferenceType:

instance creation
o  fileNamed: aString
Here is the way to use DataStream and ReferenceStream:
rr := ReferenceStream fileNamed: 'test.obj'.
rr nextPut: <your object>.
rr close.

o  new
(comment from inherited method)
report an error - Streams are created using on:-messages

o  newFileNamed: aString
Here is the way to use DataStream and ReferenceStream:
rr := ReferenceStream fileNamed: 'test.obj'.
rr nextPut: <your object>.
rr close.

o  oldFileNamed: aString
Here is the way to use DataStream and ReferenceStream:
rr := ReferenceStream oldFileNamed: 'test.obj'.
^ rr nextAndClose.

o  on: aStream
Open a new DataStream onto a low-level I/O stream.

marshalling
o  streamedRepresentationOf: anObject

o  unStream: aString

testing support
o  testWith: anObject
As a test of DataStream/ReferenceStream, write out anObject and read it back.
11/19/92 jhm: Set the file type. More informative file name.

usage example(s):

DataStream testWith: 'hi'

usage example(s):

ReferenceStream testWith: 'hi'


Instance protocol:

other
o  atEnd
Answer true if the stream is at the end.

o  byteStream

o  close
Close the stream.

o  contents

o  errorWriteReference: anInteger
PRIVATE -- Raise an error because this case of nextPut:'s perform:
shouldn't be called. -- 11/15/92 jhm

o  flush
Guarantee that any writes to me are actually recorded on disk. -- 11/17/92 jhm

o  next: anInteger
Answer an Array of the next anInteger objects in the stream.

o  nextAndClose
Speedy way to grab one object. Only use when we are inside an object binary file. Do not use for the start of a SmartRefStream mixed code-and-object file.

o  project

o  reset
Reset the stream.

o  rootObject
Return the object at the root of the tree we are filing out.

o  rootObject: anObject
Return the object at the root of the tree we are filing out.

o  setStream: aStream
PRIVATE -- Initialization method.

o  setStream: aStream reading: isReading
PRIVATE -- Initialization method.

o  size
Answer the stream's size.

o  vacantRef
Answer the magic 32-bit constant we use ***ON DISK*** as a stream 'reference
position' to identify a reference that's not yet filled in. This must be a
value that won't be used as an ordinary reference. Cf. outputReference: and
readReference. --
NOTE: We could use a different type ID for vacant-refs rather than writing
object-references with a magic value. (The type ID and value are
overwritten by ordinary object-references when weak refs are fulfilled.)

write and read
o  beginInstance: aClass size: anInteger
This is for use by storeDataOn: methods.
Cf. Object>>storeDataOn:.

o  beginReference: anObject
We're starting to read anObject. Remember it and its reference
position (if we care; ReferenceStream cares). Answer the
reference position.

o  getCurrentReference
PRIVATE -- Return the currentReference posn.
Overridden by ReferenceStream.

o  maybeBeginReference: internalObject
Do nothing. See ReferenceStream|maybeBeginReference:

o  next
Answer the next object in the stream.

usage example(s):

After reading the externalObject, internalize it.
                 #readReference is a special case. Either:
                   (1) We actually have to read the object, recursively calling
                           next, which internalizes the object.
                   (2) We just read a reference to an object already read and
                           thus already interalized.
                 Either way, we must not re-internalize the object here.

o  nextPut: anObject
Write anObject to the receiver stream. Answer anObject.

o  nextPutAll: aCollection
Write each of the objects in aCollection to the
receiver stream. Answer aCollection.

o  noteCurrentReference: typeID
PRIVATE -- If we support references for type typeID, remember
the current byteStream position so we can add the next object to
the 'objects' dictionary, and return true. Else return false.
This method is here to be overridden by ReferenceStream

o  objectAt: anInteger
PRIVATE -- Read & return the object at a given stream position. 08:18 tk anInteger is a relative file position.

o  objectIfBlocked: anObject
We don't do any blocking

o  outputReference: referencePosn
PRIVATE -- Output a reference to the object at integer stream position referencePosn (relative to basePos). To output a weak reference to an object not yet written, supply (self vacantRef) for referencePosn.

o  readArray
PRIVATE -- Read the contents of an Array.
We must do beginReference: here after instantiating the Array
but before reading its contents, in case the contents reference
the Array. beginReference: will be sent again when we return to
next, but that's ok as long as we save and restore the current
reference position over recursive calls to next.

o  readBitmap
PRIVATE -- Read the contents of a Bitmap.

o  readBoolean
PRIVATE -- Read the contents of a Boolean.
This is here only for compatibility with old data files.

o  readByteArray
PRIVATE -- Read the contents of a ByteArray.

o  readClass
Should never be executed because a DiskProxy, not a class comes in.

o  readFalse
PRIVATE -- Read the contents of a False.

o  readFloat
PRIVATE -- Read the contents of a Float.
This is the fast way to read a Float.
We support 8-byte Floats here. Non-IEEE

o  readFloatString
PRIVATE -- Read the contents of a Float string.
This is the slow way to read a Float--via its string rep'n.
It's here for compatibility with old data files.

o  readInstance
PRIVATE -- Read the contents of an arbitrary instance.
ASSUMES: readDataFrom:size: sends me beginReference: after it
instantiates the new object but before reading nested objects.
NOTE: We must restore the current reference position after
recursive calls to next.
Let the instance, not the class read the data.

o  readInteger
PRIVATE -- Read the contents of a SmallInteger.

o  readMethod
PRIVATE -- Read the contents of an arbitrary instance.
ASSUMES: readDataFrom:size: sends me beginReference: after it
instantiates the new object but before reading nested objects.
NOTE: We must restore the current reference position after
recursive calls to next.
Let the instance, not the class read the data.

o  readNil
PRIVATE -- Read the contents of an UndefinedObject.

o  readRectangle
Read a compact Rectangle.
Rectangles with values outside +/- 2047 were stored as normal objects (type=9).
They will not come here. 17:22 tk

o  readReference
Read the contents of an object reference. (Cf. outputReference:) File is not now positioned at this object.

o  readShortInst
Read the contents of an arbitrary instance that has a short header.
ASSUMES: readDataFrom:size: sends me beginReference: after it
instantiates the new object but before reading nested objects.
NOTE: We must restore the current reference position after
recursive calls to next.
Let the instance, not the class read the data.

o  readShortRef
Read an object reference from two bytes only. Original object must be in first 65536 bytes of the file. Relative to start of data. vacantRef not a possibility.

o  readString
byteStream ascii.

o  readStringOld

o  readSymbol
PRIVATE -- Read the contents of a Symbol.

o  readTrue
PRIVATE -- Read the contents of a True.

o  readUser
Reconstruct both the private class and the instance. Still used??

o  readWordArray
PRIVATE -- Read the contents of a WordArray.

o  readWordArrayForSegment
Read the contents of a WordArray ignoring endianness.

o  readWordLike
Can be used by any class that is bits and not bytes (WordArray, Bitmap, SoundBuffer, etc).
Also used to write SignedWordArray, LongArray, SignedLongArray, Unicode16Strings and Unicode32Strings.
Note that we read the class name before the size.

o  replace: original with: proxy
We may wish to remember that in some field, the original object is being replaced by the proxy. For the hybred scheme that collects with a DummyStream and writes an ImageSegment, it needs to hold onto the originals so they will appear in outPointers, and be replaced.

o  setCurrentReference: refPosn
PRIVATE -- Set currentReference to refPosn.
Noop here. Cf. ReferenceStream.

o  tryToPutReference: anObject typeID: typeID
PRIVATE -- If we support references for type typeID, and if
anObject already appears in my output stream, then put a
reference to the place where anObject already appears. If we
support references for typeID but didn't already put anObject,
then associate the current stream position with anObject in
case one wants to nextPut: it again.
Return true after putting a reference; false if the object still
needs to be put.
For DataStream this is trivial. ReferenceStream overrides this.

o  typeIDFor: anObject
Return the typeID for anObject's class.
This is where the tangle of objects is clipped to stop everything from going out.
Classes can control their instance variables by defining objectToStoreOnDataStream.
Any object in blockers is not written out. See ReferenceStream.objectIfBlocked: and DataStream nextPut:.
Morphs do not write their owners. See Morph.storeDataOn: Each morph tells itself to 'prepareToBeSaved' before writing out.

o  writeArray: anArray
PRIVATE -- Write the contents of an Array.

o  writeBitmap: aBitmap
PRIVATE -- Write the contents of a Bitmap.

o  writeBoolean: aBoolean
PRIVATE -- Write the contents of a Boolean.
This method is now obsolete.

o  writeByteArray: aByteArray
PRIVATE -- Write the contents of a ByteArray.

o  writeClass: aClass
Write out a DiskProxy for the class.
It will look up the class's name in Smalltalk in the new sustem.
Never write classes or methodDictionaries as objects.
For novel classes, front part of file is a fileIn of the new class.

o  writeFalse: aFalse
PRIVATE -- Write the contents of a False.

o  writeFloat: aFloat
PRIVATE -- Write the contents of a Float.
We support 8-byte Floats here.

o  writeFloatString: aFloat
PRIVATE -- Write the contents of a Float string.
This is the slow way to write a Float--via its string rep'n.

o  writeInstance: anObject
PRIVATE -- Write the contents of an arbitrary instance.

o  writeInteger: anInteger
PRIVATE -- Write the contents of a SmallInteger.

o  writeNil: anUndefinedObject
PRIVATE -- Write the contents of an UndefinedObject.

o  writeRectangle: anObject
Write the contents of a Rectangle. See if it can be a compact Rectangle (type=15).
Rectangles with values outside +/- 2047 were stored as normal objects (type=9). 17:22 tk

o  writeString: aString
PRIVATE -- Write the contents of a String.

o  writeStringOld: aString
PRIVATE -- Write the contents of a String.

o  writeSymbol: aSymbol
PRIVATE -- Write the contents of a Symbol.

o  writeTrue: aTrue
PRIVATE -- Write the contents of a True.

o  writeUser: anObject
Write the contents of an arbitrary User instance (and its devoted class).

o  writeWordLike: aWordArray
used to write WordArray, SignedWordArray, LongArray, SignedLongArray,
Unicode16Strings and Unicode32Strings.
Note that we put the class name before the size.



ST/X 7.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Fri, 29 Mar 2024 11:42:40 GMT