Smalltalk/X Webserver

Documentation of class 'DataStream':

Class: DataStream

Inheritance
Description
Class protocol
Instance protocol

Inheritance:

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

Package:: stx:libcompat

Category:: Compatibility-Squeak

Version:: rev: 1.30 date: 2024/01/16 17:51:59; 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.

copyrightCOPYRIGHT (c) 2011 by eXept Software AG
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

example1DataStream example1

example2An example and test of DataStream/ReferenceStream.
     11/19/92 jhm: Use self testWith:.

exampleWithPicturesDataStream exampleWithPictures

Class protocol:

cleanup

cleanUp: Re-initialize DataStream to avoid hanging onto obsolete classes

initialization

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

fileNamed: aString: Here is the way to use DataStream and ReferenceStream:
rr := ReferenceStream fileNamed: 'test.obj'.
rr nextPut: <your object>.
rr close.
new: (comment from inherited method)
report an error - Streams are created using on:-messages
newFileNamed: aString: Here is the way to use DataStream and ReferenceStream:
rr := ReferenceStream fileNamed: 'test.obj'.
rr nextPut: <your object>.
rr close.
oldFileNamed: aString: Here is the way to use DataStream and ReferenceStream:
rr := ReferenceStream oldFileNamed: 'test.obj'.
^ rr nextAndClose.
on: aStream: Open a new DataStream onto a low-level I/O stream.

marshalling

streamedRepresentationOf: anObject
unStream: aString

testing support

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

atEnd: Answer true if the stream is at the end.
byteStream
close: Close the stream.
contents
errorWriteReference: anInteger: PRIVATE -- Raise an error because this case of nextPut:'s perform:
shouldn't be called. -- 11/15/92 jhm
flush: Guarantee that any writes to me are actually recorded on disk. -- 11/17/92 jhm
next: anInteger: Answer an Array of the next anInteger objects in the stream.
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.
project
reset: Reset the stream.
rootObject: Return the object at the root of the tree we are filing out.
rootObject: anObject: Return the object at the root of the tree we are filing out.
setStream: aStream: PRIVATE -- Initialization method.
setStream: aStream reading: isReading: PRIVATE -- Initialization method.
size: Answer the stream's size.
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.)

reading

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.

write and read

beginInstance: aClass size: anInteger: This is for use by storeDataOn: methods.
Cf. Object>>storeDataOn:.
beginReference: anObject: We're starting to read anObject. Remember it and its reference
position (if we care; ReferenceStream cares). Answer the
reference position.
getCurrentReference: PRIVATE -- Return the currentReference posn.
Overridden by ReferenceStream.
maybeBeginReference: internalObject: Do nothing. See ReferenceStream|maybeBeginReference:
nextPut: anObject: Write anObject to the receiver stream.
Answer anObject
nextPutAll: aCollection: Write each of the objects in aCollection to the receiver stream.
Answer the receiver.
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
objectAt: anInteger: PRIVATE -- Read & return the object at a given stream position. 08:18 tk anInteger is a relative file position.
objectIfBlocked: anObject: We don't do any blocking
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.
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.
readBitmap: PRIVATE -- Read the contents of a Bitmap.
readBoolean: PRIVATE -- Read the contents of a Boolean.
This is here only for compatibility with old data files.
readByteArray: PRIVATE -- Read the contents of a ByteArray.
readClass: Should never be executed because a DiskProxy, not a class comes in.
readFalse: PRIVATE -- Read the contents of a False.
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
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.
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.
readInteger: PRIVATE -- Read the contents of a SmallInteger.
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.
readNil: PRIVATE -- Read the contents of an UndefinedObject.
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
readReference: Read the contents of an object reference. (Cf. outputReference:) File is not now positioned at this object.
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.
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.
readString: byteStream ascii.
readStringOld
readSymbol: PRIVATE -- Read the contents of a Symbol.
readTrue: PRIVATE -- Read the contents of a True.
readUser: Reconstruct both the private class and the instance. Still used??
readWordArray: PRIVATE -- Read the contents of a WordArray.
readWordArrayForSegment: Read the contents of a WordArray ignoring endianness.
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.
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.
setCurrentReference: refPosn: PRIVATE -- Set currentReference to refPosn.
Noop here. Cf. ReferenceStream.
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.
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.
writeArray: anArray: PRIVATE -- Write the contents of an Array.
writeBitmap: aBitmap: PRIVATE -- Write the contents of a Bitmap.
writeBoolean: aBoolean: PRIVATE -- Write the contents of a Boolean.
This method is now obsolete.
writeByteArray: aByteArray: PRIVATE -- Write the contents of a ByteArray.
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.
writeFalse: aFalse: PRIVATE -- Write the contents of a False.
writeFloat: aFloat: PRIVATE -- Write the contents of a Float.
We support 8-byte Floats here.
writeFloatString: aFloat: PRIVATE -- Write the contents of a Float string.
This is the slow way to write a Float--via its string rep'n.
writeInstance: anObject: PRIVATE -- Write the contents of an arbitrary instance.
writeInteger: anInteger: PRIVATE -- Write the contents of a SmallInteger.
writeNil: anUndefinedObject: PRIVATE -- Write the contents of an UndefinedObject.
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
writeString: aString: PRIVATE -- Write the contents of a String.
writeStringOld: aString: PRIVATE -- Write the contents of a String.
writeSymbol: aSymbol: PRIVATE -- Write the contents of a Symbol.
writeTrue: aTrue: PRIVATE -- Write the contents of a True.
writeUser: anObject: Write the contents of an arbitrary User instance (and its devoted class).
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.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Mon, 18 Nov 2024 04:19:28 GMT