# com.bea.ide.sourceeditor.model
ISourceModel Interface

public interface ISourceModel

A source model is a data structure that contains the actual text data of a given document. Generally implemented as a linked list of lines, some implementations may extend the swing AbstractDocument class, though this is not required and should not be relied upon.

## Nested Class Summary

`public static interface` | `ISourceModel.Line` A line in the source model.

## Field Summary

`public static final `String`` | `ATTRIB_LINE_DIRTY` String

## Method Summary

`public void` | `addSourceModelListener`(`ISourceModelListener` l) Adds a source model listener to the source model.
`public void` | `addUndoableEditListener`(`UndoableEditListener` l) Adds a listener to the source model that will be notified of all undoable edits that occur.
`public `Position`` | `createHoldPosition`(int offs) A variation on createPosition() which creates a Position that does not move to accomodate insertions directly on top of it.
`public `Position`` | `createPosition`(int offs) Creates a Position object to track a location in a document through user changes.
`public `String`` | `getDenormalizedText`(int offset, int length) Retrieves a subset of the source model in String form.
`public `Reader`` | `getDenormalizedTextReader`() Returns a reader for the document text that denormalizes as above.
`public int` | `getLength`()
`public `Object`` | `getLineAttribute`(int line, `Object` key) Retrives the attribute with the specified key from the specified line.
`public `ISourceModel.Line`` | `getLineByIndex`(int index) Returns the Line object at the specified index.
`public `ISourceModel.Line`` | `getLineByOffset`(int offset) Returns the Line object at the specified offset.
`public int` | `getLineCount`() Returns the number of lines in this source model.
`public int` | `getLineIndexByOffset`(int offset)
`public `String`` | `getText`(int offset, int length) Retrieves a subset of the source model in String form.
`public void` | `getText`(int offset, int length, `Segment` text) Retrieves a subset of the source model in a text Segment.
`public void` | `insertString`(int offset, `String` str, `AttributeSet` a) Inserts text into the source model.
`public void` | `remove`(int offset, int len) Deletes text from the source model.
`public void` | `removeSourceModelListener`(`ISourceModelListener` l) Removes a source model listener from the source model.
`public void` | `removeUndoableEditListener`(`UndoableEditListener` l) Removes an UndoableEditListener from the source model.
`public void` | `setLineAttribute`(int line, `Object` key, `Object` value) Sets an attribute on the specified line.
`public void` | `setReadLock`(boolean on) Acquires/releases a read lock on the model.
`public void` | `setWriteLock`(boolean on) Acquires/releases a write lock on the model.
`public void` | `touchLineAttribute`(int line, `Object` key) Does not actually change a line's attributes, but does trigger a change event to be sent to listeners, as if setLineAttribute had been called.

## Field Detail

### ATTRIB_LINE_DIRTY

    public static final String ATTRIB_LINE_DIRTY

## Method Detail

### addSourceModelListener(ISourceModelListener) Method

    public void addSourceModelListener(ISourceModelListener l)

Adds a source model listener to the source model. A source model listener is notified of all source model changes, whether they are undoable or not.

#### Parameters

l
  the listener to be added

### addUndoableEditListener(UndoableEditListener) Method

    public void addUndoableEditListener(UndoableEditListener l)

Adds a listener to the source model that will be notified of all undoable edits that occur.

#### Parameters

l
  the listener to be added

### createHoldPosition(int) Method

    public Position createHoldPosition(int offs)
         throws BadLocationException

A variation on createPosition() which creates a Position that does not move to accomodate insertions directly on top of it. This variation is not implemented by AbstractDocument, nor supported by Swing's GapContent class. The SourceEditor's DefaultSourceModel class does implement its own GapContent to support this.

#### Parameters

offs
  is the character position in the document

#### Returns

a left-biased Position mark.

#### Exceptions

``BadLocationException``

### createPosition(int) Method

    public Position createPosition(int offs)
         throws BadLocationException

Creates a Position object to track a location in a document through user changes. Insertions on top of this position will move it to the end of the inserted text. Ideally, the class that implements this interface will also extend AbstractDocument, in which case you get this for free.

#### Parameters

offs
  is the character position in the document

#### Returns

a right-biased Position mark.

#### Exceptions

``BadLocationException``

### getDenormalizedText(int, int) Method

    public String getDenormalizedText(int offset,
                                      int length)
         throws BadLocationException

Retrieves a subset of the source model in String form. The string is converted to contain the newline characters that were found in the document text when the file was loaded. Added lines will be terminated using the first newline in the original file, or the system default value for empty files. Note that the offset and length passed in are in terms of the normalized text. The resulting string may have a different length than the length passed in.

#### Parameters

offset
  a zero-based starting character offset within the file

length
  the length of text to be extracted

#### Exceptions

``BadLocationException``

### getDenormalizedTextReader() Method

    public Reader getDenormalizedTextReader()

Returns a reader for the document text that denormalizes as above. This method should generally only be called when writing document contents to disk.

### getLength() Method

    public int getLength()

#### Returns

the length, in characters, of the source model.

### getLineAttribute(int, Object) Method

    public Object getLineAttribute(int line,
                                   Object key)

Retrives the attribute with the specified key from the specified line.

#### Parameters

line
  the zero based index of the desired line

key
  an arbitrary key value, as set via a ``setLineAttribute```` call.

#### Returns

the line attribute with the specified key on the specified line. May return null is there is no such attribute on that line.

### getLineByIndex(int) Method

    public ISourceModel.Line getLineByIndex(int index)

Returns the Line object at the specified index. May be null if the line index is invalid.

#### Parameters

index
  a zero-based line index

#### Returns

a Line object, possibly null.

### getLineByOffset(int) Method

    public ISourceModel.Line getLineByOffset(int offset)

Returns the Line object at the specified offset. May be null if the offset is invalid.

#### Parameters

offset
  a zero-based character offset

#### Returns

a Line object, possibly null.

### getLineCount() Method

    public int getLineCount()

Returns the number of lines in this source model.

### getLineIndexByOffset(int) Method

    public int getLineIndexByOffset(int offset)

#### Parameters

offset
  a zero-based character offset within the file

#### Returns

the zero-based index of the line containing the offset. May return null if the offset is invalid.

### getText(int, int) Method

    public String getText(int offset,
                          int length)
         throws BadLocationException

Retrieves a subset of the source model in String form.

#### Parameters

offset
  a zero-based starting character offset within the file

length
  the length of text to be returned

#### Exceptions

``BadLocationException``

### getText(int, int, Segment) Method

    public void getText(int offset,
                        int length,
                        Segment text)
         throws BadLocationException

Retrieves a subset of the source model in a text Segment.

#### Parameters

offset
  a zero-based starting character offset within the file

length
  the length of text to be returned

text
  the Segment in which the requested text will be stored.

#### Exceptions

``BadLocationException``

### insertString(int, String, AttributeSet) Method

    public void insertString(int offset,
                             String str,
                             AttributeSet a)
         throws BadLocationException

Inserts text into the source model. Note that all document modifications will initiate a recompilation, which may generate element change events.

Be sure use "\n" for a newline, rather than an OS specific line ending or System.getProperty("line.separator"). This is editing the in-memory copy of this file. The IDE will handle line endings appropriately in reads/writes to disk.

#### Parameters

offset
  a zero-based character offset within the file

str
  the string to be inserted

a
  a collection of attributes to place on newly created lines.

#### Exceptions

``BadLocationException``

### remove(int, int) Method

    public void remove(int offset,
                       int len)
         throws BadLocationException

Deletes text from the source model. Note that all document modifications will initiate a recompilation, which may generate element change events.

#### Parameters

offset
  a zero-based character offset within the file

len
  the length of the segment to be removed

#### Exceptions

``BadLocationException``

### removeSourceModelListener(ISourceModelListener) Method

    public void removeSourceModelListener(ISourceModelListener l)

Removes a source model listener from the source model.

#### Parameters

l
  the listener to remove

### removeUndoableEditListener(UndoableEditListener) Method

    public void removeUndoableEditListener(UndoableEditListener l)

Removes an UndoableEditListener from the source model.

#### Parameters

l
  the listener to be removed.

### setLineAttribute(int, Object, Object) Method

    public void setLineAttribute(int line,
                                 Object key,
                                 Object value)

Sets an attribute on the specified line. Note that modifying a line attribute value will cause the selected line to repaint, if visible in the source view. As a result, line attributes are a common means of storing the location of line specific UI information, such as breakpoint and instruction point locations.

#### Parameters

line
  the zero-based index of the line upon which to set the attribute

key
  an arbitrary key used for retrieval of the line attribute

value
  line attribute value

### setReadLock(boolean) Method

    public void setReadLock(boolean on)

Acquires/releases a read lock on the model.

### setWriteLock(boolean) Method

    public void setWriteLock(boolean on)

Acquires/releases a write lock on the model.

### touchLineAttribute(int, Object) Method

    public void touchLineAttribute(int line,
                                   Object key)

Does not actually change a line's attributes, but does trigger a change event to be sent to listeners, as if setLineAttribute had been called. Useful when the key's value has been changed within the same object.

#### Parameters

line
  the zero based index of the desired line

key
  an arbitrary key value, as set via a ``setLineAttribute```` call. May be null to indicate multiple keys have been touched.