A document is an editable sequence of Unicode characters, which typically corresponds to the text contents of a virtual file. Line breaks in a document are always normalized to \n. The IntelliJ Platform handles encoding and line break conversions when loading and saving documents transparently.

How do I get a document?

• From an action: e.getData(PlatformDataKeys.EDITOR).getDocument()
• From a virtual file: FileDocumentManager.getDocument(). This call forces the document content to be loaded from disk if it wasn't loaded previously; if you're only interested in open documents or documents which may have been modified, use FileDocumentManager.getCachedDocument() instead.
• From a PSI file: PsiDocumentManager.getInstance().getDocument() or PsiDocumentManager.getInstance().getCachedDocument()

What can I do with a Document?

You may perform any operations that access or modify the file contents on "plain text" level (as a sequence of characters, not as a tree of Java elements).

Where does a Document come from?

Document instances are created when some operation needs to access the text contents of a file (in particular, this is needed to build the PSI for a file). Also, document instances not linked to any virtual files can be created temporarily, for example, to represent the contents of a text editor field in a dialog.

How long does a Document persist?

Document instances are weakly referenced from VirtualFile instances. Thus, an unmodified Document instance can be garbage-collected if it isn't referenced by anyone, and a new instance will be created if the document contents is accessed again later. Storing Document references in long-term data structures of your plugin will cause memory leaks.

How do I create a Document?

If you need to create a new file on disk, you don't create a Document: you create a PSI file and then get its Document. If you need to create a Document instance which isn't bound to anything, you can use EditorFactory.createDocument.

How do I get notified when Documents change?

• Document.addDocumentListener allows you to receive notifications about changes in a particular Document instance.
• EditorFactory.getEventMulticaster().addDocumentListener allows you to receive notifications about changes in all open documents.
• FileDocumentManager.addFileDocumentManagerListener allows you to receive notifications when any Document is saved or reloaded from disk.

What are the rules of working with Documents?

The general read/write action rules are in effect. In addition to that, any operations which modify the contents of the document must be wrapped in a command (CommandProcessor.getInstance().executeCommand()). executeCommand() calls can be nested, and the outermost executeCommand call is added to the undo stack. If multiple documents are modified within a command, undoing this command will by default show a confirmation dialog to the user.

If the file corresponding to a Document is read-only (for example, not checked out from the version control system), document modifications will fail. Thus, before modifying the Document, it is necessary to call ReadonlyStatusHandler.getInstance(project).ensureFilesWritable() to check out the file if necessary.

All text strings passed to Document modification methods (setText, insertString, replaceString) must use only \n as line separators.