'Document' describes a document which may be displayed in a java swing widget, or any other place where a document might be queried and modified. It uses a 'Content' object to model the text itself, allowing the usage of varying algorithms for performance reasons.

Both the Document and Content interfaces allow for getting a 'Position' object, which can be relied on for providing the same point in the text (e.g., a position created at the end of the document will always stay at the end of the document, even if text is added or removed). The interfaces don't provide methods for working with the content in terms of those Position objects; you have to call 'int getOffset()' on the Position, and pass that offset into the document.

This works just fine for the default models (S''''''tringContent and G''''''apBufferContent), which are both array based. But what if you're dealing with a linked list or a tree based model, that don't use offsets as their primary navigation methods? Well, you're stuck with keeping track of each position object you pass out, and maintaining the correct offset. You can't use special values, because the views may (and often do) rely on being able to do use those offsets to determine sizes, usually so that they can provide the right parameters to the Document methods... negative values and values larger than the content length generate errors.

This is not to say that the ability to reference a section by index shouldn't be provided, on the contrary, this is a necessary function. But the positions shouldn't expose their offsets; this assumes that a model which is array based is being used, and therefore makes using an alternate model much more difficult than necessary.