As part of a research I'm working on, I'm looking for public APIs that only work correctly when you apply a certain sequence of actions on them.
For example, the
java.nio.channels.SocketChannel class, from the Java standard library, only works correctly with sequences such as
open() -> connect() -> read() -> read() -> close(). A more complete demonstration if how it may be used may be represented in the following graph:
Additional examples of Java standard library APIs that require certain sequences are
java.io.PrintStream (very similar to the one above) and
java.util.Iterator (which requires a
next() call between every two
remove() calls, thus enforcing a certain sequence).
So, does you favorite API for doing X also behave that way? I would very much like to know about additional APIs that require a certain method sequence for correct usage; especially classes that are not part of the Java standard library. The more complex the sequence(s) required, the better.
Some APIs require a sequence that spans across multiple classes, for example:
X x = new X(); x.setup(); Y y = x.createNewY(); Z z = new Z(y); z.doSomething();
These examples are also interesting, but I'm mostly looking for sequences that all appear in the same class.
EDIT added bounty for greater visibility. I'm sure many of you have encountered many APIs that will match this description - I would really appreciate some good examples.