mirrors/cdt
1
0
Fork 0
mirror of https://github.com/eclipse-cdt/cdt synced 2025-08-28 18:53:20 +02:00
Code Issues Wiki Activity

[cleanup] Add @noimplement and similar API Tools Javadoc Markup

Browse source
This commit is contained in:
Martin Oberhuber 2008-03-28 14:27:50 +00:00
parent ee32242b1a
commit 14af215d50
25 changed files with 1349 additions and 1320 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/IRSECoreRegistry.java
View file

@ -18,10 +18,11 @@ package org.eclipse.rse.core;
/**
* Interface for RSE core registry. Clients should use this interface as the starting point for querying and
* manipulating model objects in the RSE framework.
* Interface for RSE core registry. Clients should use this interface as the
* starting point for querying and manipulating model objects in the RSE
* framework.
*
* This interface is not intended to be implemented by clients.
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface IRSECoreRegistry {

7
rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/IRSESystemType.java
View file

@ -29,9 +29,10 @@ import org.osgi.framework.Bundle;
* Interface for a system type. Constants are defined for various system types.
* These constants are kept in sync with definitions in plugin.xml.
* <p>
* This interface is not intended to be implemented by clients. System type
* implementations must subclass {@link AbstractRSESystemType} rather than
* implementing this interface directly.
* @noimplement This interface is not intended to be implemented by clients.
* System type implementations must subclass
* {@link AbstractRSESystemType} rather than implementing this
* interface directly.
* </p>
*/
public interface IRSESystemType extends IAdaptable {

6
rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/model/ISystemHostPool.java
View file

@ -22,14 +22,14 @@ import org.eclipse.rse.core.IRSESystemType;
import org.eclipse.rse.core.IRSEUserIdConstants;
/**
* An ordered list of connections ({@link IHost} objects), owned by an {@link ISystemProfile}.
* An ordered list of connections ({@link IHost} objects), owned by an
* {@link ISystemProfile}.
* <p>
* Implementations of this interface are expected to be thread-safe in the sense
* that integrity of the host list is maintained even if multiple threads call
* multiple methods in this interface concurrently.
* </p><p>
* This interface is not intended to be implemented by clients.
* </p>
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface ISystemHostPool extends IRSEPersistableContainer {

27
rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/model/ISystemRegistry.java
View file

@ -52,17 +52,15 @@ import org.eclipse.rse.core.subsystems.ISubSystemConfigurationProxy;
import org.eclipse.rse.internal.core.RSECoreRegistry;
/**
* Registry or front door for all remote system connections.
* There is a singleton of the class implementation of this interface.
* To get it, call the {@link org.eclipse.rse.core.RSECorePlugin#getTheSystemRegistry()}.
* Registry or front door for all remote system connections. There is a
* singleton of the class implementation of this interface. To get it, call the
* {@link org.eclipse.rse.core.RSECorePlugin#getTheSystemRegistry()}.
* <p>
* The idea here is that connections are grouped by system profile. At any
* time, there is a user-specified number of profiles "active" and connections
* from each active profile are worked with.
* </p>
* <p>
* This interface is not intended to be implemented by clients.
* The idea here is that connections are grouped by system profile. At any time,
* there is a user-specified number of profiles "active" and connections from
* each active profile are worked with.
* </p>
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface ISystemRegistry extends ISchedulingRule, IAdaptable, ISystemViewInputProvider {
@ -825,14 +823,17 @@ public interface ISystemRegistry extends ISchedulingRule, IAdaptable, ISystemVie
/**
* Marks all filters for this subsystem as stale to prevent caching
* @param subsystem
*
* @param subsystem the subsystem to work on
*/
public void invalidateFiltersFor(ISubSystem subsystem);
/**
* Marks all filters for this subsystem the contain resourceParent as stale to prevent caching
* @param resourceParent
* @param subsystem
* Marks all filters for this subsystem that contain resourceParent as stale
* to prevent caching
*
* @param resourceParent a remote resource object
* @param subsystem the subsystem to work on
*/
public void invalidateFiltersFor(Object resourceParent, ISubSystem subsystem);

9
rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/core/subsystems/ISubSystemConfiguration.java
View file

@ -36,11 +36,10 @@ import org.eclipse.rse.services.IService;
/**
* Subsystem Configuration interface.
*
* <p>
* This interface is not intended to be implemented by clients. Subsystem
* configuration implementations must subclass SubSystemConfiguration
* rather than implementing this interface directly.
* </p>
* @noimplement This interface is not intended to be implemented by clients.
* Subsystem configuration implementations must subclass
* SubSystemConfiguration rather than implementing this interface
* directly.
*/
public interface ISubSystemConfiguration extends ISystemFilterPoolManagerProvider, IRSEPersistableContainer {
// ---------------------------------

45
rse/plugins/org.eclipse.rse.core/src/org/eclipse/rse/internal/core/filters/SystemFilterPoolManager.java
View file

@ -39,8 +39,7 @@ import org.eclipse.rse.core.references.IRSEBaseReferencingObject;
import org.eclipse.rse.logging.Logger;
/**
* A filter pool manager manages filter pools.
* It is used to
* A filter pool manager manages filter pools. It is used to
* <ul>
* <li>Get a list of existing filter pools
* <li>Create filter pools
@ -49,11 +48,11 @@ import org.eclipse.rse.logging.Logger;
* <li>Rename filter pools
* </ul>
* <p>
* The filter pool manager ensures that
* changes to filters and pools are
* The filter pool manager ensures that changes to filters and pools are
* committed and events are fired properly.
* <p>
* This class is not intended to be subclassed by clients.
*
* @noextend This class is not intended to be subclassed by clients.
*/
public class SystemFilterPoolManager extends RSEPersistableObject implements ISystemFilterPoolManager {
private ISystemFilterPoolManagerProvider caller = null;
@ -122,7 +121,7 @@ public class SystemFilterPoolManager extends RSEPersistableObject implements ISy
protected boolean singleFilterStringOnly = SINGLE_FILTER_STRING_ONLY_EDEFAULT;
protected List pools = new ArrayList(3);
// protected List pools = null;
// protected List pools = null;
/**
* Constructor
@ -330,17 +329,17 @@ public class SystemFilterPoolManager extends RSEPersistableObject implements ISy
ISystemFilterPool[] result = new ISystemFilterPool[pools.size()];
pools.toArray(result);
return result;
// //System.out.println("Inside getSFPools for mgr "+getName()+". poolArray null? "+(poolArray==null));
// if ((poolArray == null) || (getPools().size() != poolArray.length)) {
// List pools = getPools();
// poolArray = new ISystemFilterPool[pools.size()];
// Iterator i = pools.iterator();
// int idx = 0;
// while (i.hasNext())
// poolArray[idx++] = (ISystemFilterPool) i.next();
// //System.out.println("Pool array created. length = "+poolArray.length);
// }
// return poolArray;
// //System.out.println("Inside getSFPools for mgr "+getName()+". poolArray null? "+(poolArray==null));
// if ((poolArray == null) || (getPools().size() != poolArray.length)) {
// List pools = getPools();
// poolArray = new ISystemFilterPool[pools.size()];
// Iterator i = pools.iterator();
// int idx = 0;
// while (i.hasNext())
// poolArray[idx++] = (ISystemFilterPool) i.next();
// //System.out.println("Pool array created. length = "+poolArray.length);
// }
// return poolArray;
}
/**
@ -359,10 +358,10 @@ public class SystemFilterPoolManager extends RSEPersistableObject implements ISy
/*
* Call this to invalidate array cache after any activity
*/
// private void invalidatePoolCache() {
// poolArray = null;
// poolNames = null;
// }
// private void invalidatePoolCache() {
// poolArray = null;
// poolNames = null;
// }
/**
* Create a new filter pool.
@ -393,9 +392,9 @@ public class SystemFilterPoolManager extends RSEPersistableObject implements ISy
pool.setSystemFilterPoolManager(this);
pool.setStringsCaseSensitive(areStringsCaseSensitive());
pool.setSupportsDuplicateFilterStrings(isSetSupportsDuplicateFilterStrings() && supportsDuplicateFilterStrings());
// List pools = getPools();
// List pools = getPools();
pools.add(pool);
// invalidatePoolCache();
// invalidatePoolCache();
commit(pool);
if ((caller != null) && !suspendCallbacks) {
caller.filterEventFilterPoolCreated(pool);

7
rse/plugins/org.eclipse.rse.files.ui/src/org/eclipse/rse/files/ui/resources/ISystemRemotePath.java
View file

@ -17,13 +17,12 @@
package org.eclipse.rse.files.ui.resources;
/**
* This interface defines a remote path. It is not intended to be implemented by
* clients.
* This interface defines a remote path.
*
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface ISystemRemotePath {
/**
* Get the profile name.
* @return the profile name

29
rse/plugins/org.eclipse.rse.files.ui/src/org/eclipse/rse/files/ui/resources/UniversalFileTransferUtility.java
View file

@ -87,6 +87,7 @@ import org.eclipse.rse.internal.files.ui.ISystemFileConstants;
import org.eclipse.rse.internal.files.ui.resources.SystemFileNameHelper;
import org.eclipse.rse.internal.files.ui.resources.SystemRemoteEditManager;
import org.eclipse.rse.internal.subsystems.files.core.ISystemFilePreferencesConstants;
import org.eclipse.rse.internal.ui.dialogs.CopyRunnable;
import org.eclipse.rse.services.clientserver.SystemEncodingUtil;
import org.eclipse.rse.services.clientserver.archiveutils.ArchiveHandlerManager;
import org.eclipse.rse.services.clientserver.archiveutils.ISystemArchiveHandler;
@ -108,7 +109,6 @@ import org.eclipse.rse.subsystems.files.core.subsystems.RemoteFileSubSystem;
import org.eclipse.rse.subsystems.files.core.util.ValidatorFileUniqueName;
import org.eclipse.rse.ui.RSEUIPlugin;
import org.eclipse.rse.ui.SystemBasePlugin;
import org.eclipse.rse.internal.ui.dialogs.CopyRunnable;
import org.eclipse.rse.ui.dialogs.SystemRenameSingleDialog;
import org.eclipse.rse.ui.messages.SystemMessageDialog;
import org.eclipse.swt.widgets.Display;
@ -117,10 +117,8 @@ import org.eclipse.ui.PlatformUI;
/**
* Utility class for doing file transfers on universal systems.
*
* Clients may use this class, but not instantiate or subclass it.
*
* @noextend
* @noinstantiate
* @noextend This class is not intended to be subclassed by clients.
* @noinstantiate This class is not intended to be instantiated by clients.
*/
public class UniversalFileTransferUtility
{
@ -133,11 +131,18 @@ public class UniversalFileTransferUtility
private static final int CANCEL_ALL = 16;
/**
* @param severity
* @param pluginId
* @param code
* @param message
* @param exception
* Creates a new RenameStatus object. The created status has no
* children.
*
* @param severity the severity; one of <code>OK</code>,
* <code>ERROR</code>, <code>INFO</code>,
* <code>WARNING</code>, or <code>CANCEL</code>
* @param pluginId the unique identifier of the relevant plug-in
* @param code the plug-in-specific status code, or <code>OK</code>
* @param message a human-readable message, localized to the current
* locale
* @param exception a low-level exception, or <code>null</code> if not
* applicable
*/
public RenameStatus(int severity, String pluginId, int code, String message, Throwable exception) {
super(severity, pluginId, code, message, exception);
@ -1226,7 +1231,7 @@ public class UniversalFileTransferUtility
return uploadResourceFromWorkspace(srcFileOrFolder, targetFolder, monitor, true);
}
/**
/**
* Perform a copy via drag and drop.
* @param workspaceSet the objects to be copied. If the target and sources are not on the same system, then this is a
* temporary object produced by the doDrag.
@ -2735,7 +2740,7 @@ public class UniversalFileTransferUtility
return uploadResourceFromWorkspace(srcFileOrFolder, targetFolder, monitor);
}
/**
/**
* Perform a copy via drag and drop.
* @param workspaceSet the objects to be copied. If the target and sources are not on the same system, then this is a
* temporary object produced by the doDrag.

8
rse/plugins/org.eclipse.rse.files.ui/src/org/eclipse/rse/internal/files/ui/resources/SystemRemoteMarker.java
View file

@ -23,13 +23,13 @@ import org.eclipse.rse.files.ui.resources.ISystemRemoteMarker;
import org.eclipse.rse.files.ui.resources.ISystemRemoteResource;
/**
* This class is an internal implementation of the ISystemRemoteMarker interface.
* It is not intended to be implemented by clients.
* This class is an internal implementation of the ISystemRemoteMarker
* interface.
*
* @noextend This class is not intended to be subclassed by clients.
*/
public class SystemRemoteMarker implements ISystemRemoteMarker {
/**
* Resource with which this marker is associated.
*/

19
rse/plugins/org.eclipse.rse.importexport/src/org/eclipse/rse/internal/importexport/files/RemoteExportWizard.java
View file

@ -25,25 +25,28 @@ import org.eclipse.ui.IWorkbench;
import org.eclipse.ui.IWorkbenchPage;
/**
* Standard workbench wizard for exporting resources from the workspace
* to the local file system.
* Standard workbench wizard for exporting resources from the workspace to the
* local file system.
* <p>
* This class may be instantiated and used without further configuration;
* this class is not intended to be subclassed.
* This class may be instantiated and used without further configuration.
* </p>
* <p>
* Example:
*
* <pre>
* IWizard wizard = new RemoteExportWizard();
* wizard.init(workbench, selection);
* WizardDialog dialog = new WizardDialog(shell, wizard);
* dialog.open();
* </pre>
* During the call to <code>open</code>, the wizard dialog is presented to the
* user. When the user hits Finish, the user-selected workspace resources
* are exported to the user-specified location in the local file system,
* the dialog closes, and the call to <code>open</code> returns.
*
* During the call to <code>open</code>, the wizard dialog is presented to
* the user. When the user hits Finish, the user-selected workspace resources
* are exported to the user-specified location in the local file system, the
* dialog closes, and the call to <code>open</code> returns.
* </p>
*
* @noextend This class is not intended to be subclassed by clients.
*/
public class RemoteExportWizard extends AbstractSystemWizard implements IExportWizard {
private IStructuredSelection selection;

9
rse/plugins/org.eclipse.rse.importexport/src/org/eclipse/rse/internal/importexport/files/RemoteFileImportOperation.java
View file

@ -52,11 +52,10 @@ import org.eclipse.ui.dialogs.IOverwriteQuery;
// Similar to org.eclipse.ui.wizards.datatransfer.ImportOperation
/**
* An operation which does the actual work of copying objects from the local file
* system into the workspace.
* <p>
* This class may be instantiated; it is not intended to be subclassed.
* </p>
* An operation which does the actual work of copying objects from the local
* file system into the workspace.
*
* @noextend This class is not intended to be subclassed by clients.
*/
public class RemoteFileImportOperation extends WorkspaceModifyOperation {
private static final int POLICY_DEFAULT = 0;

11
rse/plugins/org.eclipse.rse.importexport/src/org/eclipse/rse/internal/importexport/files/RemoteImportWizard.java
View file

@ -28,22 +28,25 @@ import org.eclipse.ui.IWorkbench;
* Standard workbench wizard for importing resources from the local file system
* into the workspace.
* <p>
* This class may be instantiated and used without further configuration;
* this class is not intended to be subclassed.
* This class may be instantiated and used without further configuration.
* </p>
* <p>
* Example:
*
* <pre>
* IWizard wizard = new RemoteImportWizard();
* wizard.init(workbench, selection);
* WizardDialog dialog = new WizardDialog(shell, wizard);
* dialog.open();
* </pre>
* During the call to <code>open</code>, the wizard dialog is presented to the
* user. When the user hits Finish, the user-selected files are imported
*
* During the call to <code>open</code>, the wizard dialog is presented to
* the user. When the user hits Finish, the user-selected files are imported
* into the workspace, the dialog closes, and the call to <code>open</code>
* returns.
* </p>
*
* @noextend This class is not intended to be subclassed by clients.
*/
public class RemoteImportWizard extends AbstractSystemWizard implements IImportWizard {
private IWorkbench workbench;

5
rse/plugins/org.eclipse.rse.services/clientserver/org/eclipse/rse/services/clientserver/java/BasicClassFileParser.java
View file

@ -41,9 +41,10 @@ import org.eclipse.rse.internal.services.clientserver.java.StringInfo;
import org.eclipse.rse.internal.services.clientserver.java.UTF8Info;
/**
* This is a basic class file parser that returns a package name from a class file.
* This is a basic class file parser that returns a package name from a class
* file.
* <p>
* This class is not intended to be subclassed by clients.
* @noextend This class is not intended to be subclassed by clients.
*/
public class BasicClassFileParser {

2
rse/plugins/org.eclipse.rse.services/clientserver/org/eclipse/rse/services/clientserver/java/ClassFileUtil.java
View file

@ -24,7 +24,7 @@ import java.io.InputStream;
/**
* Singleton class for obtaining various information about class files.
* <p>
* This class is not intended to be subclassed by clients.
* @noextend This class is not intended to be subclassed by clients.
*/
public class ClassFileUtil {

30
rse/plugins/org.eclipse.rse.services/src/org/eclipse/rse/services/files/IFileService.java
View file

@ -37,22 +37,24 @@ import org.eclipse.rse.services.IService;
import org.eclipse.rse.services.clientserver.messages.SystemMessageException;
/**
* A IFileService is an abstraction of a file service that runs over some sort of connection.
* It can be shared among multiple instances of a subsystem. At some point this file
* service layer may become official API but for now it is experimental. Each
* subsystem is currently responsible for layering an abstraction over whatever it
* wants to construct as a service.
* A IFileService is an abstraction of a file service that runs over some sort
* of connection. It can be shared among multiple instances of a subsystem. At
* some point this file service layer may become official API but for now it is
* experimental. Each subsystem is currently responsible for layering an
* abstraction over whatever it wants to construct as a service.
* <p>
* This is a very bare bones definition. A real definition would probably have changed
* terminology, use URI's rather than Strings, and have much more robust error handling.
* </p><p>
* Implementers of this interface will have to either be instantiated, initialized, or
* somehow derive a connection as part of its state.
* </p><p>
* This interface is not intended to be implemented by clients. File service
* implementations must subclass {@link AbstractFileService} rather than implementing
* this interface directly.
* This is a very bare bones definition. A real definition would probably have
* changed terminology, use URI's rather than Strings, and have much more robust
* error handling.
* </p>
* <p>
* Implementers of this interface will have to either be instantiated,
* initialized, or somehow derive a connection as part of its state.
* </p>
* @noimplement This interface is not intended to be implemented by clients.
* File service implementations must subclass
* {@link AbstractFileService} rather than implementing this
* interface directly.
*/
public interface IFileService extends IService
{

5
rse/plugins/org.eclipse.rse.subsystems.files.core/src/org/eclipse/rse/internal/subsystems/files/core/model/SystemFileTransferModeMapping.java
View file

@ -23,7 +23,10 @@ import org.eclipse.rse.subsystems.files.core.model.ISystemFileTransferModeMappin
/**
* An internal class. Clients must not instantiate or subclass it.
* An internal class.
*
* @noextend This class is not intended to be subclassed by clients.
* @noinstantiate This class is not intended to be instantiated by clients.
*/
public class SystemFileTransferModeMapping implements ISystemFileTransferModeMapping, Cloneable {

5
rse/plugins/org.eclipse.rse.subsystems.files.core/src/org/eclipse/rse/internal/subsystems/files/core/model/SystemFileTransferModeRegistry.java
View file

@ -49,7 +49,10 @@ import org.eclipse.ui.XMLMemento;
/**
* An internal class. Clients must not instantiate or subclass it.
* An internal class.
*
* @noextend This class is not intended to be subclassed by clients.
* @noinstantiate This class is not intended to be instantiated by clients.
*/
public class SystemFileTransferModeRegistry implements ISystemFileTransferModeRegistry {

3
rse/plugins/org.eclipse.rse.subsystems.files.core/src/org/eclipse/rse/subsystems/files/core/model/RemoteFileUtility.java
View file

@ -35,7 +35,8 @@ import org.eclipse.rse.subsystems.files.core.subsystems.IRemoteFileSubSystemConf
/**
* Public utility class for dealing with remote file subsystems.
*
* Clients may use this class, but not instantiate or subclass it.
* @noextend This class is not intended to be subclassed by clients.
* @noinstantiate This class is not intended to be instantiated by clients.
*/
public class RemoteFileUtility
{

13
rse/plugins/org.eclipse.rse.ui/UI/org/eclipse/rse/internal/ui/view/SystemComboBoxCellEditor.java
View file

@ -30,15 +30,14 @@ import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Control;
/**
* A slight variation of the Eclipse-supplied ComboBoxCellEditor class,
* which allows the input array to be changed dynamically.
* A slight variation of the Eclipse-supplied ComboBoxCellEditor class, which
* allows the input array to be changed dynamically.
* <p>
* A cell editor that presents a list of items in a combo box.
* The cell editor's value is the zero-based index of the selected
* item.
* <p>
* This class may be instantiated; it is not intended to be subclassed.
* A cell editor that presents a list of items in a combo box. The cell editor's
* value is the zero-based index of the selected item.
* </p>
*
* @noextend This class is not intended to be subclassed by clients.
*/
public class SystemComboBoxCellEditor extends CellEditor
{

2
rse/plugins/org.eclipse.rse.ui/model/org/eclipse/rse/ui/internal/model/SystemRegistryUI.java
View file

@ -65,7 +65,7 @@ import org.eclipse.ui.part.ResourceTransfer;
/**
* Registry and control center for RSE UI related operations.
*
* This class is not intended to be subclassed by clients.
* @noextend This class is not intended to be subclassed by clients.
*/
public class SystemRegistryUI implements ISystemRegistryUI {

5
rse/plugins/org.eclipse.rse.ui/model/org/eclipse/rse/ui/model/ISystemRegistryUI.java
View file

@ -31,9 +31,8 @@ import org.eclipse.swt.widgets.Shell;
/**
* Registry and control center for RSE UI related operations.
* <p>
* This interface is not intended to be implemented by clients.
* </p>
*
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface ISystemRegistryUI extends ISystemShellProvider {

8
terminal/org.eclipse.tm.terminal.view/src/org/eclipse/tm/internal/terminal/view/PageBook.java
View file

@ -15,12 +15,10 @@ import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Control;
/**
* A pagebook is a composite control where only a single control is visible
* at a time. It is similar to a notebook, but without tabs.
* <p>
* This class may be instantiated; it is not intended to be subclassed.
* </p>
* A pagebook is a composite control where only a single control is visible at a
* time. It is similar to a notebook, but without tabs.
*
* @noextend This class is not intended to be subclassed by clients.
*/
public class PageBook extends Composite {
private StackLayout fLayout;

13
terminal/org.eclipse.tm.terminal/src/org/eclipse/tm/internal/terminal/provisional/api/ITerminalControl.java
View file

@ -17,15 +17,16 @@ import org.eclipse.swt.widgets.Shell;
/**
* Represents the terminal view as seen by a terminal connection.
*
* <p> Not to be implemented by clients.
* @author Michael Scharf
* <p>
* <strong>EXPERIMENTAL</strong>. This class or interface has been added as
* part of a work in progress. There is no guarantee that this API will
* work or that it will remain the same. Please do not use this API without
* consulting with the <a href="http://www.eclipse.org/dsdp/tm/">Target Management</a> team.
* part of a work in progress. There is no guarantee that this API will work or
* that it will remain the same. Please do not use this API without consulting
* with the <a href="http://www.eclipse.org/dsdp/tm/">Target Management</a>
* team.
* </p>
*
* @author Michael Scharf
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface ITerminalControl {

41
terminal/org.eclipse.tm.terminal/src/org/eclipse/tm/terminal/model/ITerminalTextData.java
View file

@ -12,12 +12,13 @@ package org.eclipse.tm.terminal.model;
/**
* A writable matrix of characters and {@link Style}. This is intended to be the
* low level representation of the text of a Terminal. Higher layers are responsible
* to fill the text and styles into this representation.
*
* <p><b>Note: </b> Implementations of this interface has to be thread safe.
* <p><b>Note: </b> This interface is not intended to be implemented by clients.
* A writable matrix of characters and {@link Style}. This is intended to be
* the low level representation of the text of a Terminal. Higher layers are
* responsible to fill the text and styles into this representation.
* <p>
* <b>Note: </b> Implementations of this interface has to be thread safe.
* </p>
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface ITerminalTextData extends ITerminalTextDataReadOnly {
@ -68,20 +69,20 @@ public interface ITerminalTextData extends ITerminalTextDataReadOnly {
* @param line
*/
void cleanLine(int line);
// /**
// * @param line
// * @return true if this line belongs to the previous line but is simply
// * wrapped.
// */
// boolean isWrappedLine(int line);
//
// /**
// * Makes this line an extension to the previous line. Wrapped lines get folded back
// * when the width of the terminal changes
// * @param line
// * @param extendsPreviousLine
// */
// void setWrappedLine(int line, boolean extendsPreviousLine);
// /**
// * @param line
// * @return true if this line belongs to the previous line but is simply
// * wrapped.
// */
// boolean isWrappedLine(int line);
//
// /**
// * Makes this line an extension to the previous line. Wrapped lines get folded back
// * when the width of the terminal changes
// * @param line
// * @param extendsPreviousLine
// */
// void setWrappedLine(int line, boolean extendsPreviousLine);
/**
* Shifts some lines up or down. The "empty" space is filled with <code>'\000'</code> chars

113
terminal/org.eclipse.tm.terminal/src/org/eclipse/tm/terminal/model/ITerminalTextDataSnapshot.java
View file

@ -13,62 +13,73 @@ package org.eclipse.tm.terminal.model;
/**
* This class maintains a snapshot of an instance of {@link ITerminalTextData}.
* While the {@link ITerminalTextData} continues changing, the snapshot remains
* unchanged until the next snapshot is taken by calling {@link #updateSnapshot(boolean)}.
* This is important, because the {@link ITerminalTextData} might get
* modified by another thread. Suppose you would want to draw the content of
* the {@link ITerminalTextData} using the following loop:
* unchanged until the next snapshot is taken by calling
* {@link #updateSnapshot(boolean)}. This is important, because the
* {@link ITerminalTextData} might get modified by another thread. Suppose you
* would want to draw the content of the {@link ITerminalTextData} using the
* following loop:
*
* <pre>
* for(int line=0;line&lt;term.getHeight();line++)
* for(int column=0; column&lt;term.getWidth();column++)
* drawCharacter(column,line,term.getChar(column,line),term.getStyle(column,line));
* for (int line = 0; line &lt; term.getHeight(); line++)
* for (int column = 0; column &lt; term.getWidth(); column++)
* drawCharacter(column, line, term.getChar(column, line), term.getStyle(column, line));
* </pre>
* This might fail because the background thread could change the dimensions of the
* {@link ITerminalTextData} while you iterate the loop. One solution would be to
* put a <code>synchronized(term){}</code> statement around the code. This has
* two problems: 1. you would have to know about the internals of the synchronisation
* of {@link ITerminalTextData}. 2. The other thread that changes {@link ITerminalTextData}
* is blocked while the potentially slow drawing is done.
*
* This might fail because the background thread could change the dimensions of
* the {@link ITerminalTextData} while you iterate the loop. One solution would
* be to put a <code>synchronized(term){}</code> statement around the code.
* This has two problems: 1. you would have to know about the internals of the
* synchronisation of {@link ITerminalTextData}. 2. The other thread that
* changes {@link ITerminalTextData} is blocked while the potentially slow
* drawing is done.
* <p>
* <b>Solution:</b> Take a snapshot of the terminal and use the snapshot to draw
* the content. There is no danger that the data structure get changed while
* you draw. There are also methods to find out what has changed to minimize
* the number of lines that get redrawn.</p>
*
* <p><b>Drawing optimization</b>: To optimize redrawing of changed lines, this class keeps
* track of lines that have changed since the previous snapshot.</p>
*
* <pre>
* // iterate over the potentially changed lines
* for(int line=snap.getFirstChangedLine();line&lt;=snap.getLastChangedLine();line++)
* // redraw only if the line has changed
* if(snap.hasLineChanged(line))
* for(int column=0; column&lt;snap.getWidth();column++)
* drawCharacter(column,line,snap.getChar(column,line),snap.getStyle(column,line));
* </pre>
*
* <p><b>Scroll optimization:</b> Often new lines are appended at the bottom of the
* terminal and the rest of the lines are scrolled up. In this case all lines would be
* marked as changed. To optimize for this
* case, {@link #updateSnapshot(boolean)} can be called with <code>true</code> for
* the <code>detectScrolling</code> parameter. The object will keep track of scrolling.
* The UI must <b>first</b> handle the scrolling and then use the {@link #hasLineChanged(int)}
* method to determine scrolling:
* <pre>
* // scroll the visible region of the UI <b>before</b> drawing the changed lines.
* doUIScrolling(snap.getScrollChangeY(),snap.getScrollChangeN(),snap.getScrollChangeShift());
* // iterate over the potentially changed lines
* for(int line=snap.getFirstChangedLine();line&lt;=snap.getFirstChangedLine();line++)
* // redraw only if the line has changed
* if(snap.hasLineChanged(line))
* for(int column=0; column&lt;snap.getWidth();column++)
* drawCharacter(column,line,snap.getChar(column,line),snap.getStyle(column,line));
* </pre>
* <b>Solution:</b> Take a snapshot of the terminal and use the snapshot to
* draw the content. There is no danger that the data structure get changed
* while you draw. There are also methods to find out what has changed to
* minimize the number of lines that get redrawn.
* </p>
*
* <p><b>Note</b>: This interface is not intended to be implemented by clients.</p>
* <p><b>Threading Note</b>: This class is not thread save! All methods have to be called by
* the a same thread, that created the instance by calling
* {@link ITerminalTextDataReadOnly#makeSnapshot()}. </p>
* <p>
* <b>Drawing optimization</b>: To optimize redrawing of changed lines, this
* class keeps track of lines that have changed since the previous snapshot.
* </p>
*
* <pre>
* // iterate over the potentially changed lines
* for (int line = snap.getFirstChangedLine(); line &lt;= snap.getLastChangedLine(); line++)
* // redraw only if the line has changed
* if (snap.hasLineChanged(line))
* for (int column = 0; column &lt; snap.getWidth(); column++)
* drawCharacter(column, line, snap.getChar(column, line), snap.getStyle(column, line));
* </pre>
*
* <p>
* <b>Scroll optimization:</b> Often new lines are appended at the bottom of
* the terminal and the rest of the lines are scrolled up. In this case all
* lines would be marked as changed. To optimize for this case,
* {@link #updateSnapshot(boolean)} can be called with <code>true</code> for
* the <code>detectScrolling</code> parameter. The object will keep track of
* scrolling. The UI must <b>first</b> handle the scrolling and then use the
* {@link #hasLineChanged(int)} method to determine scrolling:
*
* <pre>
* // scroll the visible region of the UI &lt;b&gt;before&lt;/b&gt; drawing the changed lines.
* doUIScrolling(snap.getScrollChangeY(), snap.getScrollChangeN(), snap.getScrollChangeShift());
* // iterate over the potentially changed lines
* for (int line = snap.getFirstChangedLine(); line &lt;= snap.getFirstChangedLine(); line++)
* // redraw only if the line has changed
* if (snap.hasLineChanged(line))
* for (int column = 0; column &lt; snap.getWidth(); column++)
* drawCharacter(column, line, snap.getChar(column, line), snap.getStyle(column, line));
* </pre>
* </p>
* <p>
* <b>Threading Note</b>: This class is not thread safe! All methods have to be
* called by the a same thread, that created the instance by calling
* {@link ITerminalTextDataReadOnly#makeSnapshot()}.
* </p>
*
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface ITerminalTextDataSnapshot extends ITerminalTextDataReadOnly {
/**