org.abora.gold.nkernel
Class FeWork

java.lang.Object
  |
  +--org.abora.gold.java.AboraHeaper
        |
        +--org.abora.gold.xpp.basic.Heaper
              |
              +--org.abora.gold.nkernel.FeRangeElement
                    |
                    +--org.abora.gold.nkernel.FeWork

Direct Known Subclasses:

FeClub

public class FeWork

extends FeRangeElement

A persistent identity for a changeable object.

Field Summary

protected boolean	amWaiting
protected ID	myAuthor
protected BeWork	myBeWork
protected FeKeyMaster	myKeyMaster
protected PrimSet	myRevisionDetectors
protected PrimSet	myStatusDetectors

Fields inherited from class org.abora.gold.xpp.basic.Heaper

AllBlasts, BecomeMap, GarbageCount, InGC, InitializedClasses, InitializingClasses, LastMemory, NextClientRequestNumber, NotOneElementSignal, PackageTable, PromiseNameTable, StringHashSBoxes

Fields inherited from class org.abora.gold.java.AboraHeaper

ActiveClubs, CurrentAuthor, CurrentBertCanopyCache, CurrentBertCrum, CurrentChunk, CurrentGrandMap, CurrentKeyMaster, CurrentPacker, CurrentSensorCanopyCache, CurrentServer, CurrentSession, CurrentSessions, CurrentTrace, InitialEditClub, InitialOwner, InitialReadClub, InitialSponsor, InsideTransactionFlag

Constructor Summary

FeWork(BeWork be)

Method Summary

void	addRevisionDetector(FeRevisionDetector detector) Essential.
void	addSponsors(IDRegion clubs)
void	addStatusDetector(FeStatusDetector detector) Essential.
FeRangeElement	again() Essential.
static void	bomb(FeWork CHARGE)
boolean	canMakeIdentical(FeRangeElement newIdentity) Essential.
boolean	canRead() Return whether you have read permission.
boolean	canReadHistory() self canRead or CurrentKeyMaster has authority of the historyClub
boolean	canRevise() Return whether the BeWork is grabbed by you through this FeWork. Note: Be careful of synchronization problems, since the permissions may change before you try to actually revise it, causing you to lose your grab.
ID	currentAuthor()
void	destruct() Classes should implement this message rather than a destructor.
ID	editClub() Essential.
FeEdition	edition() Essential.
void	endorse(CrossRegion additionalEndorsements) Essential.
CrossRegion	endorsements() Essential.
ID	fetchAuthor()
BeRangeElement	fetchBe() If this has a reified Be object, then return it, else NULL
ID	getAuthor()
BeRangeElement	getOrMakeBe() An individual BeRangeElement for this identity.
void	grab() Essential.
ID	grabber() Essential.
ID	historyClub() Essential.
static void	info() {void CLIENT} addRevisionDetector: detector {PrRevisionDetector} {void CLIENT} addStatusDetector: detector {PrStatusDetector} {BooleanVar CLIENT} canRead {BooleanVar CLIENT} canRevise {ID CLIENT} editClub {FeEdition CLIENT} edition {void CLIENT} endorse: added {CrossRegion} {CrossRegion CLIENT} endorsements {void CLIENT} grab {ID CLIENT} grabber {ID CLIENT} historyClub {ID CLIENT} lastRevisionAuthor {IntegerVar CLIENT} lastRevisionNumber {IntegerVar CLIENT} lastRevisionTime {ID CLIENT} readClub {void CLIENT} release {void CLIENT} removeEditClub {void CLIENT} removeReadClub {void CLIENT} removeRevisionDetector: detector {PrRevisionDetector} {void CLIENT} removeStatusDetector: detector {PrStatusDetector} {void CLIENT} requestGrab {void CLIENT} retract: removed {CrossRegion} {void CLIENT} revise: newEdition {FeEdition} {FeEdition CLIENT} revisions {void CLIENT} setEditClub: club {ID} {void CLIENT} setHistoryClub: club {ID | NULL} {void CLIENT} setReadClub: club {ID} {void CLIENT} sponsor: clubs {IDRegion} {IDRegion CLIENT} sponsors {void CLIENT} unsponsor: clubs {IDRegion}
ID	lastRevisionAuthor() The ID of the author of the last revision of this Work to its current Edition, or its creation if it hasn't been revised since.
IntegerVar	lastRevisionNumber() The sequence number of the last revision of this Work to its current Edition, or its creation if it hasn't been revised since.
IntegerVar	lastRevisionTime() The time of the last revision of this Work to its current Edition, or its creation if it hasn't been revised since.
void	lock()
ID	lockingClub()
static Heaper	make(FeEdition contents) Essential.
void	makeIdentical(FeRangeElement newIdentity) Essential.
static FeWork	on(BeWork be)
void	printOn(java.io.PrintWriter oo)
ID	readClub() Essential.
void	release() Essential.
void	removeEditClub() Essential.
void	removeLastRevisionDetector() Essential.
void	removeLastStatusDetector() Essential.
void	removeReadClub() Essential.
void	removeSponsors(IDRegion clubs)
void	requestGrab() Essential.
void	requestLock() Essential.
void	retract(CrossRegion removedEndorsements) Essential.
void	revise(FeEdition newEdition) Essential.
FeRevisionDetector	revisionDetector() Essential.
FeEdition	revisions() Return the revision trail of the receiver.
void	setEditClub(ID club) Essential.
void	setHistoryClub(ID club) Essential.
void	setKeyMaster(FeKeyMaster km) Essential.
void	setReadClub(ID club) Essential.
void	sponsor(IDRegion clubs) Essential.
IDRegion	sponsors() Essential.
FeStatusDetector	statusDetector() Essential.
void	triggerRevisionDetectors(FeEdition contents, ID author, IntegerVar time, IntegerVar sequence) Trigger all my immediate RevisionDetectors who can read the Work
void	unendorse(CrossRegion removedEndorsements)
void	unlock() Essential.
void	unsponsor(IDRegion clubs) Essential.
void	updateStatus() The authority of my KeyMaster has changed and I need to update my status

Methods inherited from class org.abora.gold.nkernel.FeRangeElement

actualHashForEqual, addFillDetector, becomeOther, carrier, fillDetector, inspect, isEqual, isIdentical, isSameAs, label, owner, placeHolder, relabelled, removeFillDetector, setOwner, transcluders, transcluders, transcluders, transcluders, transcluders, validateEndorsement, validateSignature, works, works, works, works

Methods inherited from class org.abora.gold.xpp.basic.Heaper

abstractDeclarationFor, abstractTypeFor, addMethodAttributeToInOf, addPackage, addPackageCategory, allClientProtocolOn, argumentTypesFor, arrow, blast, blast, BLAST, cachePromiseNameTable, cachePromiseNameTableIn, canYouBecome, cast, cleanPromiseClasses, cleanupGarbage, clientClassesDo, clientFunctionsOn, clientMethodsOn, clientProtocol, clientProtocolDo, clientProtocolOn, clientProtocolOn, collectibleClasses, compare, compileClientSubclasses, compileConstantPromiseMethods, compileCreateFromRcvr, compileEQ, compileGeneratedClassMethod, compileGeneratedMethod, compileHook, compilePromise, compilePromiseDefaultMethods, compilePromiseFluidDeclarations, compilePromiseHandlers, compilePromiseMethods, compileRequestCreateMsgInArguments, compileRequestEvaluateMsgInReturningArguments, compileRPCSpecialistEvaluateMsgForReturningArguments, compileSendSelfTo, compileSendSelfToSendHook, compileStubbleMethods, compileSubclassStubbleMethods, computeMangle, computePreorder, constantTypeValue, convert, convertCopyDeclarations, convertDeferredDeclarations, convertProxyDeclarations, convertSubclassCopyDeclarations, convertSubclassDeferredDeclarations, convertSubclassProxyDeclarations, copyReferencesToType, create, create, create, create, create, create, create, create, create, create, createRequestClassArguments, definesProxyMethods, delete, deref, destroy, destructor, enum, enumFlags, equals, exportName, fetchAttribute, fetchPackage, fetchSuperCategory, fileOutClientProtocol, findCategory, findSenderAndReceiverMethods, findTailInto, flushPromiseNameTable, foo, freezeClientClasses, freezeClientProtocol, freezeStProtocol, frozenClasses, garbageCollect, garbageCollectFrom, gcOpportunity, gcOpportunity, generatedCategory, generatePromiseNames, getCategory, getOrMakePackage, getSuperCategory, handlerSignaturesFrom, hash, hashForEqual, hasProxyMethods, info_clientClasses, info_clientSideClasses, info_promiseClasses, info_stProtocol, inGC, initializedClasses, initializingClasses, initPackages, initStringHashSBoxes, inspectPieces, instanceSize, IntegerVar, isByProxy, isConstructed, isDestructed, isEqual, isEqualOrSubclassOf, isGenerated, isIntType, isKindOf, isRawType, isUnlocked, linkTimeNonInherited, make, makeClassTable, makeFillTable, makeRequestTable, mangle, markChildren, markCount, markInstances, mayBecome, mayBecomeAnySubclassOf, new1, newX, nonCopyVariables, notWorking, pack, packageClasses, packagingCategory, parseExportName, passe, pointerToStaticMember, pointerToStaticMember, pointerToVirtualMember, preorderMax, preorderNumber, PROBLEM, problems, promiseClass, promiseDefaultValue, promiseName, promiseNameTable, promiseToAbstract, registerPackageCategory, removeGeneratedCode, removeStubbleMethods, removeSubclassGeneratedCode, removeSubclassStubbleMethods, requestProcedure, requestProceduresFrom, returnTypeFor, rootName, scheduleTermination, sendProxyTo, sendSelfTo, serverNameFor, setGC, signal, signals, smalltalkSelector, stClientProtocol, stubbleSelectorTokenReturnsArguments, subclassNonCopyVariables, takeOop, togglePromiseName, togglePromiseOfParse, unimplemented, unmangle, verifyFreeze, wipeStubble

Methods inherited from class org.abora.gold.java.AboraHeaper

asOop, basicInspect, displayString, error, hack, halt, knownBug, mightNotImplement, REQUIRES, shouldImplement, shouldNotImplement, stubbleForSubclassResponsibility, thingToDo, willNotImplement

Methods inherited from class java.lang.Object

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

Field Detail

myKeyMaster

protected FeKeyMaster myKeyMaster

myAuthor

protected ID myAuthor

amWaiting

protected boolean amWaiting

myBeWork

protected BeWork myBeWork

myStatusDetectors

protected PrimSet myStatusDetectors

myRevisionDetectors

protected PrimSet myRevisionDetectors

Constructor Detail

FeWork

public FeWork(BeWork be)

Method Detail

addStatusDetector

public void addStatusDetector(FeStatusDetector detector)

Essential. Add a detector which will be notified whenever the locking status of this Work
object changes.
See FeStatusDetector::grabbed (Work *, ID *) / released (Work *).

canRead

public boolean canRead()

Return whether you have read permission. If grabbed, returns TRUE (because a grabber can
always read); if released, then returns whether the CurrentKeyMaster has sufficient
permission to read the work. (Read or Edit permission is required.) Does not check any
other KeyMasters you may be holding.
Note: Be careful of synchronization problems, since the permissions may change between
when you ask this question and when you try to actually read the Work.

canRevise

public boolean canRevise()

Return whether the BeWork is grabbed by you through this FeWork.
Note: Be careful of synchronization problems, since the permissions may change before you
try to actually revise it, causing you to lose your grab.

grab

public void grab()

Essential. Grab the Work to prevent other clients from revising it. Requires edit
permission. Snapshots the CurrentKeyMaster and CurrentAuthor (to be used to maintain the
grab and report what was done with it). Fails if
- someone else has it grabbed
- the CurrentKeyMaster does not have edit permission
- the CurrentKeyMaster does not have signature authority of the CurrentAuthor
If this Work was already grabbed by you, then it updates the KeyMaster and Author it
holds. (If the regrab fails, the old grab will remain in effect.)
The grab will be released
- upon a release request
- if the KeyMaster loses authority to edit
- if the KeyMaster loses the signature authority of the Author
- at the end of the session
- when the FeWork object is deallocated (if an FeWork was dropped while grabbed, {by
destroying the promise for it, or by loss of connection} it will be deallocated
'eventually')

grabber

public ID grabber()

Essential. If you have edit authority, and someone has the BeWork grabbed, then return
the Club ID that was the value of his CurrentAuthor when he grabbed it; otherwise blast.
Requiring edit authority is appropriate here, because it is exactly editors who are
affected by competing grabs, and need to know who has the grab. Once the BeWork is
revised, anyone who can read the current trail can see the revision, but the grab state
doesn't necessarily imply that the BeWork will be revised soon, or ever.

release

public void release()

Essential. Release the grab on this Work; if a requestGrab had been pending, remove it.
Does nothing if it is already unlocked.

removeLastStatusDetector

public void removeLastStatusDetector()

Essential. Last detector has gone away

requestGrab

public void requestGrab()

Essential. Registers a request so that the next time this Work would have been released
and no other grab requests are outstanding the CurrentKeyMaster (as of making the request)
has edit permission, and has signature authority of the CurrentAuthor (as of making the
request), it will be grabbed by this FeWork. If this FeWork already has the Work grabbed,
then the request has no effect. To find out when the grab succeeds, place Status
Detectors on the Work. (If there are competing requestGrabs for a BeWork, the queueing of
the requests may not be FIFO, but is starvation-free.) Note that if you have a
requestGrab outstanding on a BeWork through one FeWork, and release a grab you have
through another, your requestGrab has no special priority over those of other users.

statusDetector

public FeStatusDetector statusDetector()

Essential. Return a detector which will be notified whenever the locking status of this
Work changes.
See FeStatusDetector::grabbed (Work *, ID *) / released (Work *).

edition

public FeEdition edition()

Essential. Return the current Edition. Succeeds if the Work is already grabbed, or if
the CurrentKeyMaster has either Read or Edit permission.
Note: If this is an unsponsored Work, the Edition might have been discarded, in which case
this operation will blast.

revise

public void revise(FeEdition newEdition)

Essential. Change the current Edition of this work to newEdition. The Work must be
grabbed The grabber is recorded as the author who made the revision.
(This is the fundamental write operation.)

editClub

public ID editClub()

Essential. Return the club which has permission to revise this Work. Blasts if noone can
(i.e. editor has been removed).

historyClub

public ID historyClub()

Essential. Return the club which will be recorded as the initial club for frozen Works in
the history trail. Blasts if there is no trail being generated.

readClub

public ID readClub()

Essential. Return the club which has permission to read this Work. Blasts if the read
Club has been removed (in that case, only those who have edit permission can read the
Work).

removeEditClub

public void removeEditClub()

Essential. Irrevocably remove edit permission. Requires ownership authority.

removeReadClub

public void removeReadClub()

Essential. Irrevocably remove read permission (although you should note that editors are
still able to read, if there are any). Requires ownership authority.

setEditClub

public void setEditClub(ID club)

Essential. Change who has edit permission. Requires ownership authority.
Aborts if the Work doesn't have an edit Club.

setHistoryClub

public void setHistoryClub(ID club)

Essential. Change the initial read Club for frozen Works in the trail. Requires ownership
authority. Setting it to NULL turns off the recording of history.

setReadClub

public void setReadClub(ID club)

Essential. Change who has read permission. Requires ownership authority.
Aborts if the works doesn't have a read Club.

endorse

public void endorse(CrossRegion additionalEndorsements)

Essential. Adds to the endorsements on this Work. The set of endorsements must be a
finite number of (club ID, token ID) pairs. This requires the signature authority of all
of the Clubs used to endorse; will blast and do nothing if any of the required authority
is lacking. The token IDs must not be named IDs.

endorsements

public CrossRegion endorsements()

Essential. Return all of the endorsements which have been placed on this Work and are not
currently retracted.
(Endorsements are used to filter various operations which return sets of Works. See
FeEdition::rangeTranscluders() for one way to find this work by filtering for its
endorsements.)

retract

public void retract(CrossRegion removedEndorsements)

Essential. Removes endorsements from this Work. This requires the signature authority of
all of the Clubs whose endorsements are in the list; will blast and do nothing if any of
the required authority is lacking. Ignores all endorsements which you could have removed,
but which don't happen to be there right now.

sponsor

public void sponsor(IDRegion clubs)

Essential. Add to the list of sponsors of this Work. Requires signature authority of all
of the Clubs in the set.

sponsors

public IDRegion sponsors()

Essential. All of the Clubs which are sponsoring this Work to keep it from being
discarded.
What sort of permissions does this require?

unsponsor

public void unsponsor(IDRegion clubs)

Essential. End sponsorship of this Work by all of the listed Clubs. Requires signature
authority of all of the Clubs in the set, even if they are not currently sponsors.
Should this use the CurrentKeyMaster? Or the internal KeyMaster if it is grabbed?

updateStatus

public void updateStatus()

The authority of my KeyMaster has changed and I need to update my status

triggerRevisionDetectors

public void triggerRevisionDetectors(FeEdition contents,
                                     ID author,
                                     IntegerVar time,
                                     IntegerVar sequence)

Trigger all my immediate RevisionDetectors who can read the Work

fetchAuthor

public ID fetchAuthor()

fetchBe

public BeRangeElement fetchBe()

Description copied from class: FeRangeElement

If this has a reified Be object, then return it, else NULL

Overrides:

fetchBe in class FeRangeElement

getAuthor

public ID getAuthor()

getOrMakeBe

public BeRangeElement getOrMakeBe()

Description copied from class: FeRangeElement

An individual BeRangeElement for this identity. If the object is virtualized, then
de-virtualizes it.

Overrides:

getOrMakeBe in class FeRangeElement

destruct

public void destruct()

Description copied from class: Heaper

Classes should implement this message rather than a destructor. We use this so
the destruction behavior implemented in abstract superclasses can access the
vtable of the concrete run-time type in C++. Using a message makes C++
parallel the Smalltalk semantics for delete. Destroy will actually call the destructor.

Overrides:

destruct in class Heaper

printOn

public void printOn(java.io.PrintWriter oo)

Overrides:

printOn in class Heaper

again

public FeRangeElement again()

Description copied from class: FeRangeElement

Essential. An object reflecting the current identity of this object, in case it is a
PlaceHolder that has become something else since it was received from the Server.

Overrides:

again in class FeRangeElement

canMakeIdentical

public boolean canMakeIdentical(FeRangeElement newIdentity)

Description copied from class: FeRangeElement

Essential. Whether the identity of this object could be changed to the other.
Does not check whether the CurrentKeyMaster has authority to do it.
The restrictions on this operation depend on which subclass this is, but in general
(except for PlaceHolders) an object can only become another of the same type with the same
content.

Overrides:

canMakeIdentical in class FeRangeElement

makeIdentical

public void makeIdentical(FeRangeElement newIdentity)

Description copied from class: FeRangeElement

Essential. Change the identity of this object to the other. BLAST if unsuccessful.
Requires authority of the current owner; if the operation is successful, the owner will
appear to change to that of the other object.
Also requires enough permission on newIdentity to determine, by comparing content, whether
the operation would succeed.
The restrictions on this operation depend on which subclass this is, but in general
(except for PlaceHolders) an object can only become another of the same type with the same
content.

Overrides:

makeIdentical in class FeRangeElement

addSponsors

public void addSponsors(IDRegion clubs)

currentAuthor

public ID currentAuthor()

lock

public void lock()

lockingClub

public ID lockingClub()

removeSponsors

public void removeSponsors(IDRegion clubs)

requestLock

public void requestLock()

Essential. Registers a request so that the next time this Work would have been unlocked
and the KeyMaster has edit permission, it will be locked by this client. If this client
already has it locked, then it has no effect. To find out when this happens, place Status
Detectors on the Work.

setKeyMaster

public void setKeyMaster(FeKeyMaster km)

Essential. Change the authority through which the Work is being read and revised. Blasts
if the Work is locked and the new authority is insufficient to maintain the lock.

unendorse

public void unendorse(CrossRegion removedEndorsements)

unlock

public void unlock()

Essential. Release the lock on this Work. Does nothing if it is already unlocked.

addRevisionDetector

public void addRevisionDetector(FeRevisionDetector detector)

Essential. Trigger a Detector whenever there is a revision to the Work which the
CurrentKeyMaster can see. If this detector has already been added, then the old KeyMaster
associated with it is replaced with the CurrentKeyMaster.
See RevisionDetector::revised (Edition * contents,
ID * author,
IntegerVar sequence,
IntegerVar time).

lastRevisionAuthor

public ID lastRevisionAuthor()

The ID of the author of the last revision of this Work to its current Edition, or its
creation if it hasn't been revised since. The Work must be grabbed, or the
CurrentKeyMaster must be able to exercise the authority of the Read, Edit, or History
Club.

lastRevisionNumber

public IntegerVar lastRevisionNumber()

The sequence number of the last revision of this Work to its current Edition, or its
creation if it hasn't been revised since. The Work must be grabbed, or the
CurrentKeyMaster must be able to exercise the authority of the Read, Edit, or History
Club.

lastRevisionTime

public IntegerVar lastRevisionTime()

The time of the last revision of this Work to its current Edition, or its creation if it
hasn't been revised since. The Work must be grabbed, or the CurrentKeyMaster must be able
to exercise the authority of the Read, Edit, or History Club.

removeLastRevisionDetector

public void removeLastRevisionDetector()

Essential. Inform the work that its last revision detector has gone away.

revisionDetector

public FeRevisionDetector revisionDetector()

Essential. Return a detector tht will trigger whenever there is a revision to the Work
which the CurrentKeyMaster can see.
See RevisionDetector::revised (Edition * contents,
ID * author,
IntegerVar sequence,
IntegerVar time).

revisions

public FeEdition revisions()

Return the revision trail of the receiver. The trail will be empty if no revisions have
been recorded. The trail is updated immediately when the Work is revised.
In order to get the trail, either the Work must be grabbed, or you must be a member of the
Read, Edit, or History Clubs.

canReadHistory

public boolean canReadHistory()

self canRead or CurrentKeyMaster has authority of the historyClub

bomb

public static void bomb(FeWork CHARGE)

make

public static Heaper make(FeEdition contents)

Essential. Create a new Work whose initial contents are the given Edition. The reader,
editor, owner, sponsor, and KeyMaster come from the fluid environment. If the KeyMaster
has edit permission, then the Work is initially grabbed by it.
Note: This does not assign it a global ID; that must be done separately (see
Server::assignID).

on

public static FeWork on(BeWork be)

info

public static void info()

{void CLIENT} addRevisionDetector: detector {PrRevisionDetector}
{void CLIENT} addStatusDetector: detector {PrStatusDetector}
{BooleanVar CLIENT} canRead
{BooleanVar CLIENT} canRevise
{ID CLIENT} editClub
{FeEdition CLIENT} edition
{void CLIENT} endorse: added {CrossRegion}
{CrossRegion CLIENT} endorsements
{void CLIENT} grab
{ID CLIENT} grabber
{ID CLIENT} historyClub
{ID CLIENT} lastRevisionAuthor
{IntegerVar CLIENT} lastRevisionNumber
{IntegerVar CLIENT} lastRevisionTime
{ID CLIENT} readClub
{void CLIENT} release
{void CLIENT} removeEditClub
{void CLIENT} removeReadClub
{void CLIENT} removeRevisionDetector: detector {PrRevisionDetector}
{void CLIENT} removeStatusDetector: detector {PrStatusDetector}
{void CLIENT} requestGrab
{void CLIENT} retract: removed {CrossRegion}
{void CLIENT} revise: newEdition {FeEdition}
{FeEdition CLIENT} revisions
{void CLIENT} setEditClub: club {ID}
{void CLIENT} setHistoryClub: club {ID | NULL}
{void CLIENT} setReadClub: club {ID}
{void CLIENT} sponsor: clubs {IDRegion}
{IDRegion CLIENT} sponsors
{void CLIENT} unsponsor: clubs {IDRegion}