Extension SDK 10.1.2

oracle.jdeveloper.audit.model
Class DocumentAdapter

java.lang.Object
  extended byoracle.jdeveloper.audit.model.DocumentAdapter
All Implemented Interfaces:
java.lang.Comparable, Located
Direct Known Subclasses:
TextDocumentAdapter

public abstract class DocumentAdapter
extends java.lang.Object
implements java.lang.Comparable, Located

An abstract adapter between a JDeveloper document and the Audit framework. A DocumentAdapter knows how to get the constructs from its document, and works with the Location class to identify and track constructs as documents evolve. Each concrete document adapter subclass is associated with a specific document type and a corresponding concrete DocumentTypeAdapter subclass.

Document adapters have a workspace, a project, and a URL (if two projects are audited which contain the same file, two document adapters will be created and it will be traversed twice). Document adapters have a natural order defined by comparing, in order, the long labels of workspace, project, directory, and URL.

Typically, Audit works with text documents. The TextDocumentAdapter subclass is an abstract class that provides specific support for writing document adapters for text document types.

JDeveloper allows documents and models to be accessed from multiple threads, and requires various sorts of locking protocols to ensure correctness. DocumentAdapter exposes this to the Audit framework as two kinds of transactions: read and write. The Audit framework always accesses constructs inside a read transaction, and applies fixes inside a write transaction. The default implementations of the locking methods are mostly empty; however, if the System property audit.thread is equals to "true", the default implementations do some fairly rigorous thread correctness verification. Mostly this verifies that the framework is doing what it should, but it also helps verify that analyzers, transforms, and other Audit extensions stay within their bounds.

The default implementations supplied in this class assume that workspace, project, and URL are not null. To reduce special case code in the Audit framework, however, root, workspace, and project DocumentAdapter subclasses are provided in the framework which do have null workspace, project, and/or URL. These subclasses override the default implementations.

See Also:
DocumentTypeAdapter, TextDocumentAdapter

Field Summary
protected  int index
           
protected static Log log
           
protected static boolean threading
          Transaction verification diagnostic support.
 
Constructor Summary
protected DocumentAdapter(DocumentAdapterFactory factory, DocumentTypeAdapter type)
          Creates a root document adapter.
protected DocumentAdapter(DocumentAdapterFactory factory, DocumentTypeAdapter type, DocumentAdapter workspace, DocumentAdapter project, java.net.URL url)
          Creates a normal or package document adapter.
protected DocumentAdapter(DocumentAdapterFactory factory, DocumentTypeAdapter type, DocumentAdapter workspace, Project project)
          Creates a project document adapter.
protected DocumentAdapter(DocumentAdapterFactory factory, DocumentTypeAdapter type, Workspace workspace)
          Creates a workspace document adapter.
 
Method Summary
 void beginRead()
          Begins a read transaction on this document for the current thread.
 void beginWrite(java.lang.String label)
          Begins a write transaction on this document.
 void cancelWrite()
          Cancels the current write transaction on this document.
 int compareTo(java.lang.Object object)
          Gets whether this document is less than, equal to, or greater than another using the natural order defined by this class.
protected  int compareToDocument(DocumentAdapter document)
           
protected  int compareToPackage(DocumentAdapter document)
           
protected  int compareToProject(DocumentAdapter document)
           
protected  int compareToWorkspace(DocumentAdapter document)
           
 boolean contains(Location location)
          Gets whether this document contains a location.
 boolean contains(java.lang.Object construct, Location location)
          Gets whether a construct in this document contains a location.
 void endRead()
          Ends the read transaction on this document for the current thread.
 void endWrite()
          Ends the current write transaction on this document.
 boolean equals(java.lang.Object object)
          Gets whether this document is equal to an object.
 int getColumnOffset(int offset)
          Gets the zero-based column offset of a character offset in this document, or the character offset if this document does not have lines and columns.
 java.lang.Object getConstruct(Location location)
          Gets the innermost construct containing a location in this document.
 java.lang.Object getConstruct(Location location, java.lang.Object parentConstruct)
          Gets the outermost construct containing a location within a specified construct in this document.
abstract  java.util.Iterator getContainedConstructs(java.lang.Object construct)
          Gets the constructs contained by a construct in this document.
 int getDeltaLength(int offset, int length)
          Gets the change in the number of characters between an offset and a length since this document was created.
 int getDeltaOffset(int offset)
          Gets the change in the number of characters preceding an offset since this document was created.
protected  DocumentAdapter getDirectoryDocument()
           
abstract  Location[] getElementLocations(Element element)
          Gets the locations of the constructs in this document corresponding to an IDE element.
 Location getEndLocation()
          Gets a location greater than any location in this document.
 DocumentAdapterFactory getFactory()
          Gets the factory for this document.
 int getInitialLength()
          Gets the initial length of this document.
 java.lang.String getLine(int offset)
          Gets a line of text from this document, or null if this is not a text document.
 int getLineOffset(int offset)
          Gets the line offset of a character offset in this document.
 Location getLocation()
          Gets a location less than or equal to any location in this document.
abstract  Location getLocation(java.lang.Object construct)
          Gets the location for a construct in this document.
 java.lang.String getLongLabel()
           
 PackageDirectory getPackageDirectory()
          Gets the package directory containing this document.
 Project getProject()
          Gets the project containing this document.
protected  DocumentAdapter getProjectDocument()
           
abstract  java.lang.Object getRoot()
          Gets the root construct of the Audit object model for this document.
 java.lang.String getShortLabel()
           
protected  java.util.Comparator getSiblingComparator()
           
 java.lang.String getText(int offset, int length)
          Gets text from this document, or null if this is not a text document.
 java.lang.String getTransactionLabel()
          Gets the label of the current write transaction, or null if no write transaction is in progress.
 DocumentTypeAdapter getType()
          Gets the type adapter for this document.
 java.net.URL getURL()
          Gets the URL of this document.
 Workspace getWorkspace()
          Gets the workspace containing this document.
protected  DocumentAdapter getWorkspaceDocument()
          Gets the document adapter for the workspace of this document.
 boolean isModifiable()
          Gets whether this document is modifiable.
 boolean isModified()
          Gets whether this document has been modified since this document adapter was created.
 void release()
          Releases resources used by this document.
 void setDirectory(PackageDirectory directory, DocumentAdapter document)
           
protected  void sortContainedConstructs(java.util.ArrayList list)
           
 java.lang.String toString()
           
protected  void verifyReadTransaction()
          Verifies that a read transaction is in progress.
protected  void verifyWriteTransaction()
          Verifies that a write transaction is in progress.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

log

protected static final Log log

index

protected int index

threading

protected static boolean threading
Transaction verification diagnostic support.

Constructor Detail

DocumentAdapter

protected DocumentAdapter(DocumentAdapterFactory factory,
                          DocumentTypeAdapter type)
Creates a root document adapter.


DocumentAdapter

protected DocumentAdapter(DocumentAdapterFactory factory,
                          DocumentTypeAdapter type,
                          Workspace workspace)
Creates a workspace document adapter.


DocumentAdapter

protected DocumentAdapter(DocumentAdapterFactory factory,
                          DocumentTypeAdapter type,
                          DocumentAdapter workspace,
                          Project project)
Creates a project document adapter.


DocumentAdapter

protected DocumentAdapter(DocumentAdapterFactory factory,
                          DocumentTypeAdapter type,
                          DocumentAdapter workspace,
                          DocumentAdapter project,
                          java.net.URL url)
Creates a normal or package document adapter.

Method Detail

setDirectory

public void setDirectory(PackageDirectory directory,
                         DocumentAdapter document)

getDeltaLength

public int getDeltaLength(int offset,
                          int length)
Gets the change in the number of characters between an offset and a length since this document was created.


getDeltaOffset

public int getDeltaOffset(int offset)
Gets the change in the number of characters preceding an offset since this document was created.


getEndLocation

public Location getEndLocation()
Gets a location greater than any location in this document.


getFactory

public final DocumentAdapterFactory getFactory()
Gets the factory for this document.


getInitialLength

public int getInitialLength()
Gets the initial length of this document. Gets Integer.MAX_VALUE until the document is opened.


getLocation

public Location getLocation()
Gets a location less than or equal to any location in this document. Because longer locations sort before shorter locations with the same offset, the location returned encompasses the whole document.

Specified by:
getLocation in interface Located

getLongLabel

public java.lang.String getLongLabel()

getPackageDirectory

public final PackageDirectory getPackageDirectory()
Gets the package directory containing this document.


getProject

public Project getProject()
Gets the project containing this document.


getRoot

public abstract java.lang.Object getRoot()
Gets the root construct of the Audit object model for this document. A read transaction must be active on this document.


getShortLabel

public java.lang.String getShortLabel()

getType

public final DocumentTypeAdapter getType()
Gets the type adapter for this document.


getURL

public final java.net.URL getURL()
Gets the URL of this document.


getWorkspace

public Workspace getWorkspace()
Gets the workspace containing this document.


isModifiable

public boolean isModifiable()
Gets whether this document is modifiable. The DocumentAdapter implementation returns false.


isModified

public boolean isModified()
Gets whether this document has been modified since this document adapter was created. Note that this indicates nothing about whether this document is modified relative its representation on disk.


beginRead

public void beginRead()
Begins a read transaction on this document for the current thread. The DocumentAdapter implementation normally does nothing; if thread diagnostics are enabled (System property audit.thread is "true"), it verifies that no read transaction for this document is active on the current thread.


endRead

public void endRead()
Ends the read transaction on this document for the current thread. The DocumentAdapter implementation normally does nothing; if thread diagnostics are enabled (System property audit.thread is "true"), it verifies that no write transaction is active for this document and that a read transaction for this document is active on the current thread.


beginWrite

public void beginWrite(java.lang.String label)
Begins a write transaction on this document. A read transaction must already be in progress. The DocumentAdapter implementation normally only sets the transaction label; if thread diagnostics are enabled (System property audit.thread is "true"), it verifies that a read transaction is active on the current thread for this document and that no write transaction is active for this document.

Parameters:
label - The label for this transaction and for the Undo action created created when this transaction is completed.
See Also:
getTransactionLabel()

endWrite

public void endWrite()
Ends the current write transaction on this document. The DocumentAdapter implementation normally only set the transaction label to null; if thread diagnostics are enabled (System property audit.thread is "true"), it verifies that if a write transaction is active for this document, it active on the current thread.


cancelWrite

public void cancelWrite()
Cancels the current write transaction on this document. The DocumentAdapter implementation normally only set the transaction label to null; if thread diagnostics are enabled (System property audit.thread is "true"), it verifies that if a write transaction is active for this document, it active on the current thread.


getTransactionLabel

public java.lang.String getTransactionLabel()
Gets the label of the current write transaction, or null if no write transaction is in progress.


verifyReadTransaction

protected void verifyReadTransaction()
Verifies that a read transaction is in progress. The DocumentAdapter implementation normally does nothing; if thread diagnostics are enabled (System property audit.thread is "true"), it verifies that a read transaction is active on this document for the current thread.


verifyWriteTransaction

protected void verifyWriteTransaction()
Verifies that a write transaction is in progress. The DocumentAdapter implementation normally does nothing; if thread diagnostics are enabled (System property audit.thread is "true"), it verifies that a write transaction is active on this document for the current thread.


getColumnOffset

public int getColumnOffset(int offset)
Gets the zero-based column offset of a character offset in this document, or the character offset if this document does not have lines and columns. A read transaction must be active on this document. The DocumentAdapter implementation returns the character offset.


getConstruct

public java.lang.Object getConstruct(Location location)
Gets the innermost construct containing a location in this document. The location must be in this document and a read transaction must be active on this document.

Parameters:
location - A location in this document. The DocumentAdapter implementation traverses from the root using getContainedConstructs(java.lang.Object) and the Location.contains(oracle.jdeveloper.audit.model.Location) method.

getConstruct

public java.lang.Object getConstruct(Location location,
                                     java.lang.Object parentConstruct)
Gets the outermost construct containing a location within a specified construct in this document. The location and the containing construct must be in this document, the location must be in the containing construct, and a read transaction must be active on this document.

The DocumentAdapter implementation traverses from the containing construct using getContainedConstructs(java.lang.Object) and the Location.contains(oracle.jdeveloper.audit.model.Location) method.


getContainedConstructs

public abstract java.util.Iterator getContainedConstructs(java.lang.Object construct)
Gets the constructs contained by a construct in this document. A read transacton must be active on this document.

Implementations must return an iterator which iterates the constructs in document order.

Parameters:
construct - A construct of the type of this adapter.
Returns:
An iterator of constructs from this model.

getElementLocations

public abstract Location[] getElementLocations(Element element)
Gets the locations of the constructs in this document corresponding to an IDE element. A read transaction must be active on this document.

Implementations need only deal with IDE element types that are returned by the getElementTypes method of the type adapter for this document.

Parameters:
element - an IDE Element of a type supported by this document.

getLineOffset

public int getLineOffset(int offset)
Gets the line offset of a character offset in this document. A read transaction must be active on this document. The DocumentAdapter implementation returns 0.


getLocation

public abstract Location getLocation(java.lang.Object construct)
Gets the location for a construct in this document. A read transaction must be active on this document.

Implementations must extract offset and length from the construct to create a Location.

Parameters:
construct - a construct in this document, created either by getRoot() or getContainedConstructs(java.lang.Object).

getText

public java.lang.String getText(int offset,
                                int length)
Gets text from this document, or null if this is not a text document. A read transaction must be active on this document. The DocumentAdapter implementation returns null.

Parameters:
offset - The index of the first character to return.
length - The number of characters to return.

getLine

public java.lang.String getLine(int offset)
Gets a line of text from this document, or null if this is not a text document. A read transaction must be active on this document. The DocumentAdapter implementation returns null.

Parameters:
offset - The index of a character in the line to return.

equals

public boolean equals(java.lang.Object object)
Gets whether this document is equal to an object. Documents created by different DocumentAdapterFactory instances cannot be compared.


compareTo

public int compareTo(java.lang.Object object)
Gets whether this document is less than, equal to, or greater than another using the natural order defined by this class. Documents created by different DocumentAdapterFactory instances cannot be compared. The DocumentAdapter implementation delegates to compareToDocument(oracle.jdeveloper.audit.model.DocumentAdapter).

Specified by:
compareTo in interface java.lang.Comparable
Parameters:
object - The document with which to compare this document.
Throws:
java.lang.ClassCastException - if the object is not a DocumentAdapter.

compareToDocument

protected final int compareToDocument(DocumentAdapter document)

compareToPackage

protected final int compareToPackage(DocumentAdapter document)

compareToProject

protected final int compareToProject(DocumentAdapter document)

compareToWorkspace

protected final int compareToWorkspace(DocumentAdapter document)

contains

public boolean contains(Location location)
Gets whether this document contains a location.

Parameters:
location - The Location to test.

contains

public boolean contains(java.lang.Object construct,
                        Location location)
Gets whether a construct in this document contains a location.

Parameters:
construct - The construct in this document to test.
location - The Location to test.

getSiblingComparator

protected java.util.Comparator getSiblingComparator()

getWorkspaceDocument

protected DocumentAdapter getWorkspaceDocument()
Gets the document adapter for the workspace of this document.

Returns:

getProjectDocument

protected DocumentAdapter getProjectDocument()

getDirectoryDocument

protected DocumentAdapter getDirectoryDocument()

sortContainedConstructs

protected void sortContainedConstructs(java.util.ArrayList list)

release

public void release()
Releases resources used by this document.


toString

public java.lang.String toString()

Extension SDK

 

Copyright © 1997, 2004, Oracle. All rights reserved.