JSR-121 Change Log

These are the changes to the specification since Community Review.

Note that some of these changes mention items that are not visible in the draft specification. Special "@todo" and "@issue" tags are sometimes present in the Expert Group's internal  spec versions.

12/13/2002

  1. Typos in FAQ
  2. Hyperlink typos in has{Started,Exited,Terminated} method doc
  3. IsolateEvent.ExitReason.UNCAUGHT_EXCEPT  renamed UNCAUGHT_EXCEPTION
  4. IsolateMessageDispatcher.shutDown renamed shutdown
  5. Made IsolateDispatcher.Listener.receiveFailed signature consistent with messageReceived
  6. Removed J2ME optionality tag accidently added to IsolateMessage.getComposite
  7. To avoid problems with J2ME's lack of the 1.4 J2SE exception chaining feature, added getCause() methods to IsolateResourceError, IsolateStartupException, and LinkSerializationException.
  8. Corrected J2ME subset lists

12/12/2002

  1. Added Isolate methods hasStarted and hasExited and renamed isTerminated to hasTerminated
  2. Renamed Isolate methods getContext to currentIsolateContext, getIOBindings to currentIsolateIOBindings, and getIsolateMessages to currentIsolateStartMessages.
  3. Clarified async Isolate.halt and exit semantics
  4. Removed mistaken JNDI reference from isolate package doc.
  5. Added caveat about additional permissions for Isolate.exit and halt (e.g. "ExitVM" also needed to terminated current isolate)
  6. Changed IsolatePermission(String,String) ctor 2nd param from "unused and should be null" to "unused and ignored but null suggested".
  7. Numerous fixes to doc of null constructor, factory and method parameters.
  8. Acknowledgement list added to isolate package doc for posterity.
  9. ** IsolateMessage.newPipe*ChannelMessage need disclamier Added "platform default provider" disclaimer to both.
  10. ** IsolateMessage.newFileChannelMessage need disclamier Added "platform default provider" disclaimer
  11. ** IsolateEvent.ExitReason Made constructor private (had default, public constructor)
  12. ** IsolateEvent.Type Made constructor private (had default, public constructor) close on Link/LinkChannel indistinguishable:
  13. Added doc to Link.getChannel
  14. Added doc to LinkChannel class-level doc main" method on new isolate class must be public:
  15. Added 2x "public" to para in class-level doc Added 2x "public" to 1st para of long constructor
  16. IsolateEvent.equals() needs some polishing: Say object must be an IsolateEvent with same "type" and same "source isolate"
  17. IsolateMessageListener -> IsolateMessageDispatcher.Listener: One fixed in IsolateMessageDispatcher class-level doc
  18. Isolate.newEventLink need not say "either Isolate is terminated": changed to "this Isolate is terminated"
  19. Wrong method names on Pipe class Isolate stdio examples: Fixed.  Also fixed IsolateMessage constructor names for pipes.
  20. Need NPE on newEventLink:
  21. Added null entries in initial messages array:
  22. Added IsolateMessage.EMPTY_MESSAGE is a singleton
  23. Added IsolateMessageVisitor.visitEmptyMessage()
  24. TransientPreferences override base methods that throw BackingStoreException?: Added wrappers for keys, clear, childrenNames, nodeExists, removeNode, flush, sync exportNode, and exportSubtree.
  25. LinkSerializationException.j missing @params on constructors Added to both constructors Removed bodies from constructors
  26. IsolateStartupException.j missing @params on printRemoteStackTrace Added @params and @throws NPE to both printRemoteStackTrace methods
  27. * Expanded discussion of Selectors in the class-level javadoc for LinkChannel.
  28. * Documented the use of OP_READ (resp. OP_WRITE) and isOpen to detect link closure on the receiver (resp. sender) side of the link in the class-level javadoc for LinkChannel.
  29. * Added openLinkChannel, openEventLinkChannel, isSender and isReceiver to LinkChannel allowing LinkChannels to be used independently of the corresponding Link.
  30. * Clarified correspondance between Links and LinkChannels in the class- level javadoc for LinkChannel.
  31. * Added the @return for LinkChannel.getLink.
  32. * Documented the effect of serialization errors when sending composite messages which contain serializable messages in the javadoc for Link.send.
  33. * Emphasized that the contents of the message array supplied to IsolateMessage.newCompositeMessage is copied on creation and no reference to the array is retained.

12/9/2002

  1. FAQ updates
  2. Cleanup javadoc tags
  3. Improvements to spec "public review dress rehearsal" format
  4. More fixes to J2ME subset doc
  5. (the rest of these changes relate to IsolateMessageDispatcher)
  6. <code></code> fixups
  7. Put hyperlinks in the example code.
  8. Note that add, remove, shutdown are reentrant and can be invoked by listener callbacksFix minor bug in final example.
  9. Note on add() that exceptions will cause receiveFailed to be invoked.  Spell out that link will be removed before callbacks are invoked.
  10. Move this para to one before previous para.
  11. Add <font></font> stuff to LinkChannel references in add() doc.
  12. Note that an IllegalArgumentException will be thrown if given link is not receivable on in current isolate (add())
  13. Expand Listener class-doc to talk about exceptions.
  14. Add IsolateMessageDispatcher parameter to Listener.messageReceived.  Makes it much easier to remove a link from a dispatcher in response to a user-defined EOF token.
  15. Expand doc for Listener.receiveFailed.  Note that all checked and run-time exceptions documented in Link.receive will be caught here.
  16. Note that link will have been removed before callback is invoked.

  17.  

12/8/2002

  1. Spell checking/fixing make targets, first round of spelling corrections
  2. ClosedLinkException.j: Tweak first sentence
  3. ClosedLinkException.j: Replace list of occurances/causes with paras.
  4. IsolateMessage.j: a/an fixes
  5. IsolateMessageVisitor.j: <code></code> blocks
  6. IsolateMessageVisitor.j: a/an fixes
  7. IsolatePermission.j: Remove "Composite" from list of permission types Add note a
  8. bout send.Composite and receive.Composite not existing.
  9. IsolateStartupException.j: Re-work main doc to be both local and remote friendly.
  10. IsolateStartupException.j: Fix longest constructor so @params match signature
  11. Link.j: <code>Link</code> -> link (and vice-versa) fixups
  12. Link.j: isSender @returns 'potentially' -> 'structurally'
  13. Link.j: fix "must first be passed" para, include the creator (NEEDS WORK)
  14. Link.j: Hyperlink "interruption" to Thread#interrupt
  15. Link.j: Add 'system-provided' to IsolateEvent in Event Link description.
  16. Link.j: "structurally able" -> "structurally allowed" on isSender/isReceiver
  17. Link.j: Fix broken first sentence on send
  18. Link.j: linkplain (vs. link) throwable cause
  19. Link.j: Add composite message security check doc to send/recv
  20. Link.j: isOpen: "non event links" -> "application links"
  21. Link.j: fix broken event-link href
  22. Link.j: newEventLink remove redundant "close if terminated" para
  23. LinkChannel.j: <code></code>
  24. LinkChannel.j: Re-write initial sentence of validOps based on superclass doc
  25. LinkChannel.j: Add SecurityException to send/recv
  26. LinkSerializationException.j: Tweak first sentence.
  27. LinkSerializationException.j: Add <code></code> around LinkSerializationException
  28. TransientPreferences.j: Refer users to Preferences instead of AbstractPreferences

  29.  

12/6/2002

  1. Preprocessing fix for subset generation, a few subset doc fixes
  2. Dropped "either but not both" LinkChannel blocking wording
  3. Removed unused bitser.net collateral doc reference
  4. Update doc to reflect IsolateEvent no longer being optional with J2ME
  5. Removed "and its subclasses" from discussion of Link in package.ht.
  6. Tweak Link description in package.ht because there is no longer asmall number of IO classes supported.
  7. Tweak RMI/CORBA para in Comms section in package.ht..
  8. Commented out lots of text in the expanded rationale for links in package.ht.
  9. Removed isolate enumeration from Security section in package.ht.
  10. Removed several gratuitous "&nbsp;"s from package.ht
  11. Fixed the <a name=foo></a> blocks to cover some text in package.ht
  12. Fix bug in first example in Isolate.j
  13. Add a bit of text introducing the subsections of the Isolate class-level doc.  Add a "context" doc sub-section to class-level doc.
  14. Add missing ")" to Standard IO Redirection doc in Isolate.j
  15. Fix bug in 1st example of stream redirection in Isolate.j
  16. Fix bug in 2nd example of stream redirection in Isolate.j
  17. Add hyperlinks to stdio redirection examples in Isolate.j
  18. Add that main class can be on bootstrap or extension classpaths note in Isolate long constructor doc
  19. Add missing ) to long Isolate constructor para on stdio redirection
  20. Add hyperlinks to Jar examples on isolate class doc
  21. A couple "a IsolateMessage" -> "an IsolateMessage" in Isolate.j
  22. Fix spelling of "avialable" in Isolate.start
  23. Fix missing </code> on Isolate.start's @throws IllegalStateException
  24. Change Link -> IsolateMessage is Isolate.getIOBindings @return doc
  25. Isolate.newEventLink says an IsolateResourceError will be thrown in either isolate is terminated, but Link.newEventLink throws ClosedLinkException in that case.  Switched Isolate.newEventLink to match.
  26. Isolate.getContext: there are always some default values now (e.g., the JNI one).  2nd para tweaked
  27. Isolate.getContext: changed 'org.goodness.neatfeature' to 'org.apache.neatfeature'
  28. Isolate.getContext: change "(node)" type in first table to "node", made it a hyperlink to Preferences.node()
  29. Isolate.getContext: reword first sentence of Impl-Specific preferences
  30. Isolate.getContext: Inconsistent "-ing of preference keys.  Always quoted and <code></code>'d now.
  31. Isolate.getContext: <emph></emph> is a Latex-ism, use <em></em>IsolateEvent.j: lots of a/an fixes, some <code></code> fixes
  32. IsolateEvent.j: Remove "make final" @todo, hidden constructor prevents the problems just as cleanly.
  33. IsolateEvent.j: Use "source Isolate" to more clearly differentiate the isolate which is generating events from receiver and starter.
  34. IsolateMessage.j: Missing <code></code> around IllegalStateException in newIsolateMessage()
  35. IsolateMessage.j: lots of a/an fixes (mostly "Creates a ..." / "wrap in a ...")
  36. IsolateMessage.j: newByteBufferMessage add text saying the contents of the byte buffer will be transferred!
  37. IsolateMessage.j: Tweaked the disclaimers on ServerSocket, Socket, DatagramSocket to be a bit more precise.
  38. IsolateMessage.j: newSerializableMessage rewritten before realizing that Miles already did...
  39. IsolateMessage.j: newSerializableMessage "received." -> "received message."
  40. IsolateMessage.j: newCompositeMessage: no need to check un-started isolates, as such IsolateMessages cannot be created in the first place.
  41. IsolateMessage.j: acceptVisitor @param 'r' should be 'visitor'
  42. IsolateMessage.j: clean up definition of equals
  43. IsolateMessage.j: Remove trailing '.' at end of @throws clauses
  44. IsolateMessage.j: Add many '@see newFooMessage' to getFoo methods
  45. IsolateMessage.j: Add many '@see getFoo' to newFooMessage methods
  46. IsolateMessage.j: a -> an in front of IllegalArgumentException
  47. IsolateMessage.j: tweak example description
  48. IsolateMessage.j: <code></code> missing on visitCompositeMessage
  49. IsolateMessage.j: "Visit a" -> "Visit an" on newest methods
  50. IsolateMessage.j: LinkMessage substitut-os on visitLinkMessage
  51. IsolateMessageVisitor.j: <code></code> and a/an fixes
  52. IsolateMessageVisitor.j: rename 'lm' param to 'im'
  53. IsolatePermission.j: Shorten '{link type}' to '<i>{mtype}</i>' (its shorter and the table has width problems).
  54. IsolatePermission.j: Add missing types to send/recv table entries
  55. IsolatePermission.j: Move the send/recv type text out of the table
  56. IsolatePermission.j: Note that getIOBindings and getInitialMessages are controlled by the "context" permission.
  57. IsolatePermission.j: Fix bug in isolate constructor in first example
  58. Rewrite of newSerializableMessage doc

12/4/2002

  1. Fixed preprocessing problems, getting rid of implicit oring with the sed scripts
  2. Rewrote IsolateMessage.newSerializableMessage doc
  3. Removed "not both" nonblocking part of LinkChannel reference in Link doc.
  4. First round of changes to javadoc titles, date string
  5. Changed "pronounced isolet" to just make it clear we're not idiots and are using Isolate as a noun. Users can go look up the pronunciation.
  6. Caption for bugeye diagram in isolate package doc
  7. Nuked "nonessentials" stuff off bottom of package doc.

11/26/2002

  1. Withdrew Isolate.getIsolates() while gathering more requirements related to Aggregate management
  2. Fixed doc bug added with 11/19 changes ("early out exceptions" w Link.send/receive)
  3. Put single Link copy semantics statement in the Link.send doc, removed a couple other mentions of this in other method doc
  4. Fixed a few cases where the proposed LinkChannel APIs might have been interpreted as part of the 121 spec
  5. Refactored the spec source files and arranged for automatic building of the proposed ME subet for CDC/FPv1.0. This allows for javadoc to be created that only mentions the subset API elements and their doc and should have no trace of APIs or doc mention of nio, preferences, or other functionality not supported with CDC/FPv1.0.

11/19/2002

  1. Added DatagramChannel, FileChannel, SocketChannel, ServerSocketChannel to IsolateMessage and IsolateMessageVisitor.
  2. Clarified JNI isolation discussion in isolate package doc
  3. Renamed IsolateMessage.newIsolateMessage(Link) to newLinkMessage(Link) to fix mistake put into 10/21 changes

  4.  

11/7/2002

  1. Backed out the REMOTE_CLOSE change,  added an example of how applications can send and handle an explicit "no more messages" token.
  2. All exceptions due to closure are now be reported as ClosedLinkException with a nested exception where appropriate (eg. async close, closed by interrupt).
  3. Replaced IsolateMessageDispatcher.linkClosed() with receiveFailed(), which reports all receive failure exceptions to the listener.
  4. Clarified the various exceptions and under what circumstances they can be thrown from send and receive, and how that relates to rendezvous and message transfer.
  5. Added newCompositeMessage() and getComposite() to IsolateMessage.
  6. Dropped newBidirectionalLink(). "Unidirectional" links are now "Application" links. There isn't a bidirectional link for these to contrast with any more, and the new name emphasizes that event links are largely handled by the implementation. Replaced the bidi-link example with one illustrating passing pair of one-way links via a composite message.
  7. Removed restriction on loopbacks (i.e. src isolate == dst isolate) on the remaining link types.

10/21/2002

  1. Class name changes (done by Pete S.):
  2. Brought Link.{send,receive} into line with NIO interruption semantics.
  3. Added a Link.receive REMOTE_TOKEN (backed out in a subsequent change above).
  4. LinkClosedException is no longer thrown by Link.send if the message being sent contains a closed Socket, Link etc.
  5. Link.{send,receive} are now declared to throw plain IOException.
  6. Synced LinkChannel with the Link changes.

10/14/2002

  1. Isolate.start() method changed to take an array of LinkMessage instead of array of Link.
  2. Updated examples in Link.java to show new LinkMessages
  3. As in addition to Isolate.start() throwing IsolateStartupException there can now be an underlying LinkSerializationException, doc'd that the latter exception will be chained to the former if present.
  4. Isolate.getLinks method changed to Isolate.GetLinkMessages.

10/12/2002

  1. Document behavior of invoking LinkMessageDispatcher.remove in context of a listener callback
  2. Document behavior of invoking LinkMessageDispatcher.shutdown in context of a listener callback.
  3. Allow a listener to be registered with more than one dispatcher (just a doc fix).
  4. Indicate that exceptions in listeners will propogate out through the run() method.
  5. Indicate that if run() returns normally or due to an exception, it will effectively "remove" all links (put them back into clean state).
  6. Added LinkMessageDispatcher.Listener.linkClosed.
  7. Document what happens when a link is closed, while registered with dispatcher (the link is effecitvely "removed" after the linkClosed method is invoked; linkClosed is invoked even if the link is closed before being added.).
  8. Document that Link.close is legal to invoke on link while registered with dispatcher (just to clarify the ownership of the link, anyone can legally invoke close while the link is registered.)

  9.  

10/10/2002-b

  1. Added i/o redirection usage examples.
  2. Finished doc of the 10/8 i/o bindings changes.
  3. Added "experimental" preferences "java.lang.isolate.jni-isolatation" and "java.lang.isolate.vm-isolatation" and additional usage detail to make it clear that these preferences are set by the implementation.

10/10/2002-a

  1. Added DatagramSocket, FileInputStream, FileOutputStream to LinkMessage and LinkMessageVisitor
  2. Removed inheritance of java.util.EventObject , readObject and writeObject from IsolateEvent

10/8/2002

  1. Added Isolate.getIoBindings
  2. Changed Isolate "long constructor" signature to take three LinkMessage parameters instead of an IsolateStreamBindings parameter.
  3. Removed IsolateStreamBindings class.

10/5/2002

  1. Removed all three static final ints (STARTING, EXITING, TERMINATED) from IsolateEvent class
  2. Added static inner class IsolateEvent.Type with three static factories STARTING(), EXITING(), TERMINATED()

10/6/2002

  1. The java.lang.isolate.AllocError class renamed to java.lang.isolate.IsolateResourceError for more naming uniformity.
  2. @issue added to java.nio.channels.LinkChannel proposed API suggesting throwing ClosedChannelException instead of ClosedLinkException for send/recieive methods. Requested by Sun internal review but still in discussion.*
  3. Dropped @todo about considering factory methods for Isolate class.*
  4. Fixed typo so Isolate.getLinks() requires "context" permission.
  5. Removed parameter from convenience method Isolate.newEventLink() and spec'd it to be equivalent to Link.newEventLink(this, Isolate.currentIsolate()).
  6. Replaced the org.tullmann.mpisolate.currentpid example preference in the Isolate.getContext() doc with something less provocative and fixed a typo.
  7. Added method "public Isolate getStarter()" to IsolateEvent to allow retrieval of a reference to the creating/starting isolate that caused a STARTING event. Requested by Jan Vitek and Grzegorz Czajkowski with a use case documented at the September 18, 2002 EG meeting.
  8. Changed STOPPING state to EXITING to be consistent with the Isolate.exit(int) method.
  9. For EXITING state (formerly STOPPING), removed @issue about whether the list is exhaustive.*
  10. Removed @issue about a "shutdown hooks completed" bit for IsolateEvent.ExitReason.*
  11. Removed @issue about reflection in IsolatePermission doc.*
  12. Removed @todo about supporting timeout.*
  13. Removed @todo about doc of multiple threads doing send/receive.*
  14. Expanded @issue about needing to discuss thread interruption of LInk operations with Mark Reinhold.*
  15. Expanded @issue about TransientPreferences vis a vis user/system exposure by adding Pat Tullmann's remarks.*
  16. Added doc to Link.send() and isSender() to repeat the message from the Link class doc that event links cannot be senders (i.e. impl sends, user code doesn't)
  17. Removed @todo about "events exactly once" and tacked on "independent of number of therads" to the  Link doc.
  18. Changed Link.getChannel() to throw ClosedChannelException instead of IllegalStateException for closed case and removed @todo.
  19. Added @issue wondering if Link should implement Channel.**
  20. Removed @todo to justify the "somewhat odd set of types" for LinkMessage.*
  21. Removed @todo for CharBuffer.*
  22. Removed @todo about LinkMessage.getSerializable() throwing IOException with the expectation that such a message will be chained (embedded) by a LinkSerializationException.*
  23. Changed LinkMessageDispatcher.add() doc to make it more clear that a dispatcher "owns" a link added to it and to try to clarify the situation where non-blocking i/o is used by the dispatcher implementation.
  24.  Added @todo from Laurent Daynes "Shouldn't there be a method of LinkMessageDispatcher.listener that the dispatcher should call when the listened link is closed ?" This requires more discussion by the EG.*
  25. Added doc to LinkMessageDispatcher.add/receive to say if the dispatcher has terminated these methods are simply null operations.
  26. Added doc to LinkMessageDispatcher.add to say a redundant add of the same Link/Listener pair will be ignored.

Community Review Draft published 9/19/2002