Documentos y particiones

La infraestructura de texto de la plataforma define un modelo de documento para texto y suministra un visor que visualiza el texto mediante este modelo. Empezaremos por examinar el ejemplo de editor Java y como éste utiliza este modelo.  No nos centraremos en los mecanismos básicos de la operación de registrar una extensión del editor, puesto que ya los hemos visto en la sección que describe org.eclipse.ui.editors.  En lugar de ello, observaremos los detalles específicos de la implementación de la clase editor en el ejemplo.

Proveedores de documentos y documentos

En el entorno de trabajo, un editor se abre generalmente cuando el usuario selecciona un elemento de dominio (como por ejemplo un archivo o un elemento almacenado dentro de un archivador) y lo abre.  Cuando se crea el editor, se asocia con una entrada de editor (IEditorInput) que describe el objeto editado.

El editor Java de ejemplo se abre cuando el usuario abre un archivo con la extensión "*.jav".  En este caso, la entrada del editor es IFileEditorInput.  La infraestructura de texto de la plataforma efectúa pocas presunciones acerca de la entrada del editor en sí.  Trabaja con un modelo de presentación, denominado IDocument, correspondiente a la entrada, para poder visualizar y manipular el texto de forma efectiva.

Esto significa que debe existir una forma de correlación entre el modelo de dominio esperado (la entrada del editor) y el modelo de presentación.  Esta correlación se define en un IDocumentProvider.  Dada una entrada del editor, el proveedor de documentos devuelve un IDocument adecuado.

El editor Java de ejemplo define un JavaDocumentProvider que devuelve el documento apropiado.  ¿Cómo se establece la relación entre el proveedor de documentos adecuado y la extensión "*.jav"?  Se realiza en la extensión org.eclipse.ui.documentProviders.  Esta extensión se utiliza para definir correlaciones entre tipos de archivo y proveedores de documentos.  El ejemplo define su proveedor de documentos de la forma siguiente:

   <extension
      point="org.eclipse.ui.documentProviders">
   <provider
         extensions="jav"
         class="org.eclipse.ui.examples.javaeditor.JavaDocumentProvider"
         id="org.eclipse.ui.examples.javaeditor.JavaDocumentProvider">
   </provider>
</extension>

Cuando el usuario abre un archivo que tiene la extensión especificada, el entorno de trabajo gestiona los detalles de la creación de la instancia del proveedor de documentos.  El entorno de trabajo crea una instancia del proveedor de documentos una única vez y comparte dicha instancia entre los diversos editores.

No es necesario que el conector utilice este punto de extensión para registrar su proveedor de documentos. Otra forma de asociar un proveedor de documentos con un editor consiste en dejar que el propio conector gestione el proveedor de documentos.  Esto se realiza generalmente en la clase del conector.  Cuando se define un elemento de entrada en el editor, éste solicita a su clase de conector el proveedor de documentos adecuado.  El conector puede gestionar la creación del proveedor de documentos y las referencias del mismo.  Esta técnica puede ser preferible cuando existe una inicialización especial u otros procesos implicados en el proveedor de documentos.  Consulte el ClassFileEditor de las herramientas de JDT para obtener un ejemplo. 

Una vez que el proveedor de documentos adecuado está asociado con un editor, su tarea principal consiste en crear un documento a partir de la entrada del editor y configurar un objeto apropiado para dividir el documento en particiones.  

Particiones

Vamos a examinar los documentos y particiones de JavaDocumentProvider.  Cuando se crea un documento, se crea un IDocumentPartitioner y se establece en el documento.  

protected IDocument createDocument(Object element) throws CoreException {
	IDocument document= super.createDocument(element);
	if (document != null) {
		IDocumentPartitioner partitioner= createJavaPartitioner();
		document.setDocumentPartitioner(partitioner);
		partitioner.connect(document);
	}
	return document;
}

El particionador es responsable de dividir el documento en regiones no solapadas, denominadas particiones.  Las particiones (representadas en ITypedRegion) son de utilidad para tratar de forma distinta diferentes secciones del documento con respecto a funciones tales como el resaltado de sintaxis o el formato.

En el caso del editor Java de ejemplo, el documento está dividido en particiones que representan los comentarios javadoc, los comentarios multilínea y todo lo demás.  A cada región se le asigna un tipo de contenido y su posición en el documento.  Las posiciones se actualizan a medida que el usuario edita el texto.   

Partición de documentos basada en reglas

La determinación de la implementación adecuada para un particionador de documentos corre a cargo de cada editor.  En org.eclipse.jface.text.rules se suministra soporte para la exploración de documentos basada en reglas.  La utilización de un explorador basado en reglas permite a los editores emplear el DefaultPartitioner suministrado por la infraestructura.

private IDocumentPartitioner createJavaPartitioner() {
	return new DefaultPartitioner(getJavaPartitionScanner(), TYPES);
}

RuleBasedPartitionScanner es la superclase de los exploradores basados en reglas.  Las subclases son responsables de nombrar e implementar las reglas que deben utilizarse para distinguir símbolos tales como delimitadores de línea, espacio en blanco y patrones genéricos al explorar un documento.  En el ejemplo, JavaPartitionScanner define las reglas para distinguir comentarios de línea simples, constantes de tipo carácter, javadoc, comentarios multilínea y palabras.  Esto se realiza en el constructor del explorador:

public JavaPartitionScanner() {
	super();
	IToken javaDoc= new Token(JAVA_DOC);
	IToken comment= new Token(JAVA_MULTILINE_COMMENT);

	List rules= new ArrayList();
	// Añadir regla para comentarios de línea simples.
	rules.add(new EndOfLineRule("//", Token.UNDEFINED)); 

	// Añadir regla para series y constantes de tipo carácter.
	rules.add(new SingleLineRule("\"", "\"", Token.UNDEFINED, '\\')); 
	rules.add(new SingleLineRule("'", "'", Token.UNDEFINED, '\\')); 

	// Añadir regla para palabras con mayúsculas y minúsculas especiales.
	rules.add(new WordPredicateRule(comment));

	// Añadir reglas para comentarios multilínea y javadoc.
	rules.add(new MultiLineRule("/**", "*/", javaDoc, (char) 0, true)); 
	rules.add(new MultiLineRule("/*", "*/", comment, (char) 0, true)); 

	IPredicateRule[] result= new IPredicateRule[rules.size()];
	rules.toArray(result);
	setPredicateRules(result);
}

Consulte las clases de org.eclipse.jface.text.rules para obtener más detalles acerca de la definición de reglas y los tipos de reglas disponibles.  Examinaremos de nuevo los exploradores al tratar el coloreado de sintaxis.

Modelos de anotación

Además de proporcionar un documento adecuado para una entrada del editor, otra tarea importante de un proveedor de documentos es suministrar un IAnnotationModel apropiado para utilizarlo con una entrada del editor.  Este modelo se utiliza para gestionar las anotaciones asociadas a los documentos.  Si deja que el proveedor de documentos suministre el modelo, el editor podrá utilizar un modelo adecuado para el tipo de contenido.  En la próxima sección trataremos con más detalle las anotaciones y su presentación.

Copyright IBM Corporation y otros 2000, 2003.