com.gemstone.gbj

## Class GbjCollection

- java.lang.Object
- - java.util.Observable
  - - com.gemstone.gbjgci.GbjGciReport
    - - com.gemstone.gbjgci.GbjGciObject
      - - com.gemstone.gbj.GbjObject
        - - com.gemstone.gbj.GbjCollection

- All Implemented Interfaces:
    java.lang.Cloneable

      public class GbjCollection
      extends GbjObject

  This subclass of GbjObject represents server instances of Collection or one of its subclasses, excluding subclasses of the server class AbstractDictionary. GbjCollection provides methods for manipulating collections in the server. It can create an Enumeration that performs efficient caching of the server object's contents for minimal client/server traffic during the enumeration operation. This class is not synchronized, if the application is accessing the same instance from multiple threads, the application is responsible for synchronization.

  ## GBJ 3.2 Changes

  Server classes that are subclasses of the server class Collection and whose element cannot be directly enumerated via com.gemstone.gbjgci.GbjGciObject.getObjs are no longer mapped to GbjCollection. The classes no longer mapped are server classes AbstractDicitionary, Bag, Set and subclasses thereof. If enumration of instances of those server classes is desired a new GBJ class would be needed to provide a correct implementation (ref bug 51203).
  Removed methods asSet() and asBag(), because the results would not be representable as a Collection .
  Version:
    3.2

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `GbjCollection()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.Object` | `add(java.lang.Object obj)` Add the object to the receiver, returning the object.
    `GbjCollection` | `addAll(GbjCollection obj)` Add the contents of the given collection to the receiver, returning the arg.
    `java.lang.Object` | `addAll(java.lang.Object[] obj)` Add the contents of the given collection to the receiver, returning the arg.
    `GbjObject[]` | `allElements()` Return an array holding all of the server collection's contents.
    `GbjCollection` | `asArray()` Create an extensible array with the contents of the server object
    `GbjObject` | `asByteArray()`
    `GbjCollection` | `asIdentityBag()` Create an identity bag with the contents of the server object
    `GbjCollection` | `asIdentitySet()` Create an identity set with the contents of the server object
    `GbjCollection` | `asOrderedCollection()` Create an ordered collection with the contents of the server object
    `GbjCollection` | `asSortedCollection()` Sort the server object according to <=
    `GbjCollection` | `asSortedCollection(java.lang.String sortBlock)` Use the given Smalltalk block to sort the server object.
    `GbjCollection` | `asSortedOrderedCollection()` Create an ordered collection with the sorted contents of the server object
    `GbjCollection` | `collect(java.lang.String collectBlock)` Evaluate the given block with each element of the server object returning a collection, usually of the same kind, with the results.
    `GbjObject` | `detect(java.lang.String detectBlock)` Find the first element in the server enumeration that satisfies the given block.
    `java.util.Enumeration` | `elements()` Return an Enumeration of the server object's contents.
    `void` | `exclusiveLockContents()` Lock the contents of this collection.
    `int` | `identicalOccurrencesOf(GbjObject anObject)` Return the number of occurrences of the given object in the server object
    `boolean` | `includes(GbjObject anObject)` Return whether an object equal to the argument is in the server object
    `boolean` | `includesIdentical(GbjObject anObject)` Return whether the argument is in the server object
    `boolean` | `includesValue(GbjObject anObject)` Return whether an object equal to the argument is in the server object
    `GbjObject` | `injectInto(GbjObject arg, java.lang.String block)` Evaluate the given block with the given argument plus an element of the server object.
    `boolean` | `isEmpty()` Does the server object hold anything?
    `int` | `occurrencesOf(GbjObject anObject)` Return the number of occurrences of the given object's value in the server object
    `void` | `readLockContents()` Lock the contents of this collection.
    `GbjCollection` | `reject(java.lang.String rejectBlock)` Return a collection of all the elements of the server object that do not satisfy the given block
    `GbjObject` | `remove(GbjObject obj)` Remove the given object's value from the server object, throwing an error if not found
    `GbjObject` | `removeAll(GbjCollection obj)` Remove the given collection's values from the server object, throwing an error if not found
    `GbjObject` | `removeAllIdentical(GbjCollection obj)` Remove the given objects from the server object, throwing an error if not found
    `GbjObject` | `removeIdentical(GbjObject obj)` Remove the given object from the server object, throwing an error if not found
    `void` | `removeLocksOnContents()` Release locks held on the contents of this collection.
    `GbjObject` | `removeValue(GbjObject obj)` Remove the given object's value from the server object, throwing an error if not found
    `GbjCollection` | `select(java.lang.String selectBlock)` Return a collection of all the elements of the server object that satisfy the given block
    `GbjCollection` | `sortAscending()` Return an array of the server sorted values
    `GbjCollection` | `sortAscending(java.lang.String variableName)` Sort the server object on the given instance variable
    `GbjCollection` | `sortDescending()` Return an array of the server sorted values
    `GbjCollection` | `sortDescending(java.lang.String variableName)` Sort the server object on the given instance variable
    `GbjCollection` | `sortWith(java.lang.String specs)` Sort the server object using the given GemStone sort specification
    `void` | `writeLockContents()` Lock the contents of this collection.

    - ### Methods inherited from class com.gemstone.gbj.GbjObject

      `assignToSegment, asString, at, atPut, cachedValue, canBeWritten, changeToSegment, cluster, clusterBucket, clusterDepthFirst, dbStringBufferValue, dbStringValue, deepCopy, exclusiveLock, execute, fromInteger, fromLong, getSession, immediateInvariant, in, isBehavior, isCommitted, isConnected, isInvariant, isKindOf, isMemberOf, isWritten, moveToDisk, namedInstanceVariables, nilFields, notNil, page, pageCreationTime, perform, perform, printString, readLock, remoteClass, remoteClone, remoteCopy, remoteEquals, remoteEqualsIdentical, remoteEqualsNoCase, remoteHash, remoteIdentityHash, remoteIsEquivalent, remoteSize, remoteSpecies, removeLock, respondsTo, segment, sendMsg, sendMsg, sendMsg, sendMsg, sendMsg, sendMsg, size, stringBufferValue, withOop, writeLock`

    - ### Methods inherited from class com.gemstone.gbjgci.GbjGciObject

      `bigDecimalFloatValue, bigDecimalValue, bigFractionValue, bigIntegerValue, booleanValue, bytesValue, byteValue, charValue, dateValue, debugPrint, doubleValue, equals, floatValue, getByte, getBytes, getIndexedSize, getNamedObj, getNamedObjs, getNamedSize, getObj, getObjs, getObjs, getObjType, getTotalSize, getValType, hashCode, instantValue, intValue, isString, localDateTimeValue, localDateValue, localTimeValue, longValue, named, offsetDateTimeValue, putByte, putBytes, putBytes, putNamedObj, putNamedObjs, putNamedObjs, putObj, putObjs, putObjs, shortValue, stringValue_, stringValue, toString, withOop, zonedDateTimeValue`

    - ### Methods inherited from class com.gemstone.gbjgci.GbjGciReport

      `clone, getOop, getValTypeString, isNil, isSpecial, javaClass, javaValue`

    - ### Methods inherited from class java.util.Observable

      `addObserver, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers`

    - ### Methods inherited from class java.lang.Object

      `getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### GbjCollection

          public GbjCollection()

  - ### Method Detail

    - #### elements

          public java.util.Enumeration elements()

      Return an Enumeration of the server object's contents. If the receiver is not a sequenceableCollection in GemStone, the server object's contents will be sequenced in the server.
      Returns:
        Enumeration result

    - #### allElements

          public GbjObject[] allElements()

      Return an array holding all of the server collection's contents.
      Returns:
        result Gbjobject array

    - #### add

          public java.lang.Object add(java.lang.Object obj)
                               throws GbjException

      Add the object to the receiver, returning the object.
      Parameters:
        `obj` - - a GbjObject instance or an object that the interface can convert to a server object
      Returns:
        The receiver
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### addAll

          public GbjCollection addAll(GbjCollection obj)
                               throws GbjException

      Add the contents of the given collection to the receiver, returning the arg.
      Parameters:
        `obj` - - a GbjCollection of server objects
      Returns:
        The collection of server objects added
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### addAll

          public java.lang.Object addAll(java.lang.Object[] obj)
                                  throws GbjException

      Add the contents of the given collection to the receiver, returning the arg.
      Parameters:
        `obj` - - a Java array of GbjObjects or objects that can be converted to server objects
      Returns:
        The array of objects added
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### asArray

          public GbjCollection asArray()
                                throws GbjException

      Create an extensible array with the contents of the server object
      Returns:
        The resulting server array object
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### asByteArray

          public GbjObject asByteArray()
                                throws GbjException

      Throws:
        `GbjException`

    - #### asIdentityBag

          public GbjCollection asIdentityBag()
                                      throws GbjException

      Create an identity bag with the contents of the server object
      Returns:
        The resulting server identity bag object
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### asIdentitySet

          public GbjCollection asIdentitySet()
                                      throws GbjException

      Create an identity set with the contents of the server object
      Returns:
        The resulting server identity set object
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### asOrderedCollection

          public GbjCollection asOrderedCollection()
                                            throws GbjException

      Create an ordered collection with the contents of the server object
      Returns:
        The resulting server ordered collection object
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### asSortedCollection

          public GbjCollection asSortedCollection()
                                           throws GbjException

      Sort the server object according to <=
      Returns:
        The resulting sorted collection object
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### asSortedCollection

          public GbjCollection asSortedCollection(java.lang.String sortBlock)
                                           throws GbjException

      Use the given Smalltalk block to sort the server object. The block must be in the form [:a:b | booleanExpression], for instance

           [:a:b | a address street <= b address street ]

      Parameters:
        `sortBlock` - String containing sort block
      Returns:
        The resulting sorted collection object
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### asSortedOrderedCollection

          public GbjCollection asSortedOrderedCollection()
                                                  throws GbjException

      Create an ordered collection with the sorted contents of the server object
      Returns:
        The resulting sorted collection object
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### collect

          public GbjCollection collect(java.lang.String collectBlock)
                                throws GbjException

      Evaluate the given block with each element of the server object returning a collection, usually of the same kind, with the results. For instance,

            collect("[:each | each segment owner userId]")

      Parameters:
        `collectBlock` - String containing collect block
      Returns:
        The resulting collection object
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### detect

          public GbjObject detect(java.lang.String detectBlock)
                           throws GbjException

      Find the first element in the server enumeration that satisfies the given block. For instance,

            detect("[:each | each segment owner userId = #DataCurator]")

      Parameters:
        `detectBlock` - String containing detect block
      Returns:
        The detected object
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### identicalOccurrencesOf

          public int identicalOccurrencesOf(GbjObject anObject)
                                     throws GbjException

      Return the number of occurrences of the given object in the server object
      Parameters:
        `anObject` - Given object
      Returns:
        int result
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### includes

          public boolean includes(GbjObject anObject)
                           throws GbjException

      Return whether an object equal to the argument is in the server object
      Parameters:
        `anObject` - Given object
      Returns:
        boolean result
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### includesIdentical

          public boolean includesIdentical(GbjObject anObject)
                                    throws GbjException

      Return whether the argument is in the server object
      Parameters:
        `anObject` - Given object
      Returns:
        boolean result
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### includesValue

          public boolean includesValue(GbjObject anObject)
                                throws GbjException

      Return whether an object equal to the argument is in the server object
      Parameters:
        `anObject` - Given object
      Returns:
        boolean result
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### injectInto

          public GbjObject injectInto(GbjObject arg,
                                      java.lang.String block)
                               throws GbjException

      Evaluate the given block with the given argument plus an element of the server object. Evaluate the block for remaining elements of the server object using the result of the previous evaluation as the first argument and the element as the second argument. E.g.,

           coll.injectInto(GbjGetSession().GSOne, "[:v:e | v+e]").intValue()

      Parameters:
        `arg` - Object for first inject
        `block` - Block to use for inject
      Returns:
        The final value returned by the block
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### isEmpty

          public boolean isEmpty()
                          throws GbjException

      Does the server object hold anything?
      Returns:
        boolean
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### occurrencesOf

          public int occurrencesOf(GbjObject anObject)
                            throws GbjException

      Return the number of occurrences of the given object's value in the server object
      Parameters:
        `anObject` - Given object
      Returns:
        int result
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### reject

          public GbjCollection reject(java.lang.String rejectBlock)
                               throws GbjException

      Return a collection of all the elements of the server object that do not satisfy the given block
      Parameters:
        `rejectBlock` - Block to reject on
      Returns:
        GbjCollection result
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### remove

          public GbjObject remove(GbjObject obj)
                           throws GbjException

      Remove the given object's value from the server object, throwing an error if not found
      Parameters:
        `obj` - Object to remove
      Returns:
        The receiver
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### removeIdentical

          public GbjObject removeIdentical(GbjObject obj)
                                    throws GbjException

      Remove the given object from the server object, throwing an error if not found
      Parameters:
        `obj` - Object to remove
      Returns:
        The receiver
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### removeValue

          public GbjObject removeValue(GbjObject obj)
                                throws GbjException

      Remove the given object's value from the server object, throwing an error if not found
      Parameters:
        `obj` - Object to remove
      Returns:
        The receiver
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### removeAll

          public GbjObject removeAll(GbjCollection obj)
                              throws GbjException

      Remove the given collection's values from the server object, throwing an error if not found
      Parameters:
        `obj` - Object to remove
      Returns:
        The receiver
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### removeAllIdentical

          public GbjObject removeAllIdentical(GbjCollection obj)
                                       throws GbjException

      Remove the given objects from the server object, throwing an error if not found
      Parameters:
        `obj` - Object to remove
      Returns:
        The receiver
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### select

          public GbjCollection select(java.lang.String selectBlock)
                               throws GbjException

      Return a collection of all the elements of the server object that satisfy the given block
      Parameters:
        `selectBlock` - Select block to use
      Returns:
        Result collection
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### sortAscending

          public GbjCollection sortAscending()
                                      throws GbjException

      Return an array of the server sorted values
      Returns:
        GbjCollection result
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### sortDescending

          public GbjCollection sortDescending()
                                       throws GbjException

      Return an array of the server sorted values
      Returns:
        GbjCollection result
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### sortAscending

          public GbjCollection sortAscending(java.lang.String variableName)
                                      throws GbjException

      Sort the server object on the given instance variable
      Parameters:
        `variableName` - Name of instance variable
      Returns:
        The receiver
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### sortDescending

          public GbjCollection sortDescending(java.lang.String variableName)
                                       throws GbjException

      Sort the server object on the given instance variable
      Parameters:
        `variableName` - Name of instance variable
      Returns:
        The receiver
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### sortWith

          public GbjCollection sortWith(java.lang.String specs)
                                 throws GbjException

      Sort the server object using the given GemStone sort specification
      Parameters:
        `specs` - Sort specification
      Returns:
        The receiver
      Throws:
        `GbjException` - thrown if there is a server exception

    - #### readLockContents

          public void readLockContents()
                                throws GbjException

      Lock the contents of this collection. Throws an exception with number LOCK_ERR_INCOMPLETE if all locks cannot be obtained.
      Throws:
        `GbjException` - thrown if there is a server exception
      See Also:
        `GbjGemStoneErrors.LOCK_ERR_INCOMPLETE`

    - #### writeLockContents

          public void writeLockContents()
                                 throws GbjException

      Lock the contents of this collection. Throws an exception with number LOCK_ERR_INCOMPLETE if all locks cannot be obtained.
      Throws:
        `GbjException` - thrown if there is a server exception
      See Also:
        `GbjGemStoneErrors.LOCK_ERR_INCOMPLETE`

    - #### exclusiveLockContents

          public void exclusiveLockContents()
                                     throws GbjException

      Lock the contents of this collection. Throws an exception with number LOCK_ERR_INCOMPLETE if all locks cannot be obtained.
      Throws:
        `GbjException` - thrown if there is a server exception
      See Also:
        `GbjGemStoneErrors.LOCK_ERR_INCOMPLETE`

    - #### removeLocksOnContents

          public void removeLocksOnContents()
                                     throws GbjException

      Release locks held on the contents of this collection. Objects in the collection that are not locked are ignored.
      Throws:
        `GbjException` - thrown if there is a server exception