!=========================================================================
! Copyright (C) VMware, Inc. 1986-2011.  All Rights Reserved.
!
! $Id: clusterb.gs,v 1.8 2008-01-09 22:50:09 stever Exp $
!
! Superclass Hierarchy:
!   ClusterBucket, Object.
!
!=========================================================================

removeallmethods ClusterBucket
removeallclassmethods ClusterBucket

category: 'For Documentation Installation only'
classmethod: ClusterBucket
installDocumentation

| doc txt |
doc := GsClassDocumentation newForClass: self.

txt := (GsDocText new) details:
'A ClusterBucket describes clustering behavior.  A ClusterBucket represents
 an abstract collection of pages within the repository ; the collection
 has no defined size and cannot be enumerated.' .
doc documentClassWith: txt.

txt := (GsDocText new) details:
'A SmallInteger.'.
doc documentInstVar: #_clusterId with: txt.

txt := (GsDocText new) details:
'A SmallInteger, DEPRECATED.
 In Gemstone64 v2.0, the relationship between a ClusterBucket and
 an extent is weak.  Clustering an object into a ClusterBucket will
 attempt to use the specified extentId , if the session already has a 
 free page within that extent.  
 Otherwise  DBF_ALLOCATION_MODE in Stone''s config file will
 take precedence when the session asks stone for more free pages.' .
doc documentInstVar: #extentId with: txt.

txt := (GsDocText new) details:
'A Boolean.'.
doc documentInstVar: #keepClusteredOnModify with: txt.

txt := (GsDocText new) details:
'Unconstrained, typically a String.'.
doc documentInstVar: #description with: txt.

self description: doc.
%

category: 'Accessing'
classmethod: ClusterBucket
allInstances

"Returns the collection of all instances of the receiver."

^ AllClusterBuckets
%

category: 'Accessing'
classmethod: ClusterBucket
bucketWithId: aPositiveSmallInt

"Returns the instance with the specified ID if one exists.  Generates an error
 if anInt is less than 1 or outside of the range of existing cluster buckets."

^ AllClusterBuckets at: aPositiveSmallInt
%

category: 'Instance Creation'
classmethod: ClusterBucket
new

"Creates an instance of the receiver and adds the new instance to
 AllClusterBuckets."

| newId result max |
max := System _maxClusterId .
(AllClusterBuckets size >= max) ifTrue: [
  self _error: #rtErrMaxClusterId args: max.
  ^ AllClusterBuckets at: 1 "returns default bucket"
  ] .
newId := AllClusterBuckets size + 1 .
result := super new .
result _clusterId: newId ;
       extentId: nil "attempt to keep objects in their current extent" ;
       keepClusteredOnModify: false ;
  "create an empty string for the description, so description can be
   modified later without putting the ClusterBucket in a write set."
       description: String new .

AllClusterBuckets addLast: result .
^ result
%

category: 'Instance Creation'
classmethod: ClusterBucket
newForExtent: extentId

"DEPRECATED. 
 In Gemstone64 v2.0, the relationship between a ClusterBucket and
 an extent is weak.  Clustering an object into a ClusterBucket will
 attempt to use the specified extentId , if the session already has a 
 free page within that extent.  
 Otherwise  DBF_ALLOCATION_MODE in Stone's config file will
 take precedence when the session asks stone for more free pages.
 
 Creates an instance of the receiver for clustering objects in the extent
 extentId.  The extentId argument is a positive SmallInteger in the range of
 1 to (SystemRepository numberOfExtents)."

^ self new extentId: extentId
%

category: 'Accessing'
method: ClusterBucket
clusterId

"Returns the value of the private instance variable.  This instance variable
 should only be assigned by ClusterBucket | new."

^ _clusterId
%

category: 'Accessing'
method: ClusterBucket
extentId

"Returns the value of the extentId instance variable.

 In Gemstone64 v2.0, the relationship between a ClusterBucket and
 an extent is weak.  Clustering an object into a ClusterBucket will
 attempt to use the specified extentId , if the session already has a 
 free page within that extent.  
 Otherwise  DBF_ALLOCATION_MODE in Stone's config file will
 take precedence when the session asks stone for more free pages."


^ extentId
%

category: 'Accessing'
method: ClusterBucket
keepClusteredOnModify

"This feature is not implemented in this release."

^ keepClusteredOnModify
%

category: 'Accessing'
method: ClusterBucket
description

"Returns the value of the description instance variable."

^ description
%

category: 'Updating'
method: ClusterBucket
description: anObject

"Assigns anObject (typically some kind of String object) as the description of
 the receiver."

description := anObject
%

category: 'Updating'
method: ClusterBucket
_clearClusterCache

"Private.  Any method that modifies an instance variable of a
 ClusterBucket that affects clustering behavior must send this method.  The
 instance variable description is not included in such instance variables."

<primitive: 235>
self _primitiveFailed: #_clearClusterCache .
self _uncontinuableError
%

category: 'Updating'
method: ClusterBucket
_clusterId: aSmallInteger

"Private.  For use only during instance creation."

_clusterId := aSmallInteger .
self _clearClusterCache .
%

category: 'Updating'
method: ClusterBucket
extentId: anExtentId

"DEPRECATED.  In Gemstone64 v2.0, the relationship between a ClusterBucket and
 an extent is weak.  Clustering an object into a ClusterBucket will
 attempt to use the specified extentId , if the session already has a 
 free page within that extent.  
 Otherwise  DBF_ALLOCATION_MODE in Stone's config file will
 take precedence when the session asks stone for more free pages.

 An argument of nil specifies don't care behavior.  Positive arguments are 
 an offset into the result of Repository | fileNames, thus specifying an extent.  
 Reference to an extent which does not exist will generate an error at the 
 time of executing this method.

 At the time of object modification, a non-nil extentId specifies which extent
 to attempt to put the object in (per DEPRECATED notice above).
 If the extent no longer exists, or is full,
 at the time of clustering or object modification, don't care behavior occurs."


SystemRepository validateExtentId: anExtentId .
extentId := anExtentId .
self _clearClusterCache .
%

category: 'Updating'
method: ClusterBucket
keepClusteredOnModify: aBoolean

"This feature is deferred until a future release.  Argument value of true
 is not supported in this release."

keepClusteredOnModify := false .
self _clearClusterCache .
%

category: 'Accessing the Class Format'
classmethod: ClusterBucket
firstPublicInstVar

"Returns the index of the first publicly available instance variable storage
 location, whether or not a public instance variable has actually been defined."

^ 2
%

