org.netbeans.modules.parsing.api
Class Source

java.lang.Object
  org.netbeans.modules.parsing.api.Source

public final class Source
extends Object

The Source represents one file or document.

An instance of Source can either be obtained for a FileObject or Document. If a particular FileObject and a Document are tied together in the way that the Document was loaded from the FileObject using either of them will get the same Source instance.

Please note that the infrastructure does not keep Source instances forever and they can and will be garbage collected if nobody references them. This also means that two successive Source.create calls for the same file or document will return two different Source instances if the first instance is garbage collected prior the second call.

Method Summary

static Source	create(Document document) Gets a Source instance for a Document.
static Source	create(FileObject fileObject) Gets a Source instance for a file.
Snapshot	createSnapshot() Creates a new Snapshot of the contents of this Source.
Document	getDocument(boolean forceOpen) Gets the Document represented by this source.
FileObject	getFileObject() Gets the FileObject represented by this source.
String	getMimeType() Gets this Source's mime type.
String	toString()

Methods inherited from class java.lang.Object

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

Method Detail

create

public static Source create(FileObject fileObject)

Gets a Source instance for a file. The FileObject passed to this method has to be a valid data file. There is no Source representation for a folder.

Parameters:

fileObject - The file to get Source for.

Returns:

The Source for the given file or null if the file doesn't exist.

create

public static Source create(Document document)

Gets a Source instance for a Document. This method is consistent with create(org.openide.filesystems.FileObject) in the way that they both will return the same Source instance for documents loaded from files. For example the following asserts will never fail (providing that relevant method calls return non-null).

 // #1
 Source source = Source.create(file);
 assert(source == Source.create(source.getFileObject()));
 assert(source == Source.create(source.getDocument()));

 // #2
 Source source = Source.create(document);
 assert(source == Source.create(source.getDocument()));
 assert(source == Source.create(source.getFileObject()));
 

Please note that you can get Source instance for any arbitrary document no matter if it was loaded from a file or not. However, the editor infrastructure generally does not support creation of fileless documents that are later saved and re-bound to a FileObject. If you wish to do something like that you will have to create a new Document instance loaded from the FileObject and use it instead of the original one.

Parameters:

document - The Document to get Source for.

Returns:

The Source for the given document; never null.

getMimeType

public String getMimeType()

Gets this Source's mime type. It's the mime type of the Document represented by this source. If the document has not yet been loaded it's the mime type of the FileObject.

Returns:

The mime type.

getDocument

public Document getDocument(boolean forceOpen)

Gets the Document represented by this source. This method returns either the document, which was used to obtain this Source instance in create(javax.swing.text.Document) or the document that has been loaded from the FileObject used in create(org.openide.filesystems.FileObject).

Please note that this method can return null in case that this Source was created for a file and there has not been yet a document loaded from this file.

Returns:

The Document represented by this Source or null if no document has been loaded yet.

getFileObject

public FileObject getFileObject()

Gets the FileObject represented by this source. This method returns either the file, which was used to obtain this Source instance in create(org.openide.filesystems.FileObject) or the file that the document represented by this Source was loaded from.

Please note that this method can return null in case that this Source was created for a fileless document (ie. Document instance that was not loaded from a file).

Returns:

The FileObject or null if this Source was created for a fileless document.

createSnapshot

public Snapshot createSnapshot()

Creates a new Snapshot of the contents of this Source. A snapshot is an immutable static copy of the contents represented by this Source. The snapshot is created from the document, if it exists. If the document has not been loaded yet the snapshot will be created from the file.

Returns:

The Snapshot of the current content of this source.

toString

public String toString()

Overrides:

toString in class Object