上一節我們定制了WTP StructuredTextEditor的自動提示功能特征,本節將定制另外一個功能特征即時源碼校驗。所謂源碼即時校驗,就是在用戶編輯過程中(并未保存),針對用戶編輯的內容改變做即時校驗,并給用戶即時反饋相關的錯誤或者其他類型的提示信息。在本節中,我們將以標簽的即時校驗為例,演示如何定制WTP StructuredTextEditor的源碼即時校驗。
在定制之前,我們先來看一下WTP StructuredTextEditor已有的源碼即時校驗功能:

我們看到,我們刪除</jsp:text>的瞬間,WTP StructuredTextEditor的即時校驗就給出了錯誤提示。其實我們在很多其他的編輯器,例如java源碼編輯器等,都可以看到類似的即時校驗功能。
【JFace Text Framework中相關內容】
說白了,我們的源碼編輯對應的控件就是ISourceViewer,那么這個校驗也理所當然應該是ISourceViewer所提供的一個服務。JFace Text Framework中確實針對源碼即時校驗提供了相應的機制,我們看一下相應的接口和運行原理。
【相關接口】
1、
IReconciler(org.eclipse.jface.text.reconciler.IReconciler),調解者,當文檔發生變化時,根據分區類型(如果這個概念忘記了,翻一下前面的文章)提供相應的調解策略(直接說成是驗證策略吧^_^)。
public interface IReconciler {
/**
* Installs the reconciler on the given text viewer. After this method has been
* finished, the reconciler is operational, i.e., it works without requesting
* further client actions until <code>uninstall</code> is called.
*
* @param textViewer the viewer on which the reconciler is installed
*/
void install(ITextViewer textViewer);
/**
* Removes the reconciler from the text viewer it has
* previously been installed on.
*/
void uninstall();
/**
* Returns the reconciling strategy registered with the reconciler
* for the specified content type.
*
* @param contentType the content type for which to determine the reconciling strategy
* @return the reconciling strategy registered for the given content type, or
* <code>null</code> if there is no such strategy
*/
IReconcilingStrategy getReconcilingStrategy(String contentType);
}
2、
IReconcilingStrategy(org.eclipse.jface.text.reconciler.IReconcilingStrategy),真正的驗證邏輯角色。結合上面的
IReconciler接口介紹,我們可以清晰的看出這是,是策略模式的一個應用(驗證邏輯角色這個概念的具體實現隨著分區類型的不同而可能變化,IReconciler可以看成是IReconcilingStrategy的管理者,在需要應用源碼即時驗證的上下文中,給定具體分區類型向IReconciler索取驗證策略)。
public interface IReconcilingStrategy {
/**
* Tells this reconciling strategy on which document it will
* work. This method will be called before any other method
* and can be called multiple times. The regions passed to the
* other methods always refer to the most recent document
* passed into this method.
*
* @param document the document on which this strategy will work
*/
void setDocument(IDocument document);
/**
* Activates incremental reconciling of the specified dirty region.
* As a dirty region might span multiple content types, the segment of the
* dirty region which should be investigated is also provided to this
* reconciling strategy. The given regions refer to the document passed into
* the most recent call of {@link #setDocument(IDocument)}.
*
* @param dirtyRegion the document region which has been changed
* @param subRegion the sub region in the dirty region which should be reconciled
*/
void reconcile(DirtyRegion dirtyRegion, IRegion subRegion);
/**
* Activates non-incremental reconciling. The reconciling strategy is just told
* that there are changes and that it should reconcile the given partition of the
* document most recently passed into {@link #setDocument(IDocument)}.
*
* @param partition the document partition to be reconciled
*/
void reconcile(IRegion partition);
}
到這里,關于調解(驗證)的兩個最重要的接口也介紹了,那這個
IReconciler(
IReconcilingStrategy)怎么和source viewer聯系起來呢?
3、
SourceViewerConfiguration(org.eclipse.jface.text.source.SourceViewerConfiguration)中定義了提供IReconciler實現的接口。
public class SourceViewerConfiguration {
/**
* Returns the reconciler ready to be used with the given source viewer.
* This implementation always returns <code>null</code>.
*
* @param sourceViewer the source viewer to be configured by this configuration
* @return a reconciler or <code>null</code> if reconciling should not be supported
*/
public IReconciler getReconciler(ISourceViewer sourceViewer) {
return null;
}
//其他方法省略
}
【執行原理】
疑問:雖然SourceViewerConfiguration中定義了提供IReconciler實現的接口,但是我們目前看到只是一個靜態關系啊。當source viewer中用戶對文檔內容進行編輯的時候,IReconciler怎么會被自動調用嗎?
我們知道,在IEditorPart(ITextEditor)創建控件(createPartControl)的過程中,會對其含有的source viewer進行配置(config),而SourceViewerConfiguration會在這個配置過程中被應用,我們簡要看一下SourceViewer.config實現:
public void configure(SourceViewerConfiguration configuration) {
if (getTextWidget() == null)
return;
setDocumentPartitioning(configuration.getConfiguredDocumentPartitioning(this));
// install content type independent plug-ins
fPresentationReconciler= configuration.getPresentationReconciler(this);
if (fPresentationReconciler != null)
fPresentationReconciler.install(this);
fReconciler= configuration.getReconciler(this);
if (fReconciler != null)
fReconciler.install(this);
//其他代碼省略
}
也就是說,我們提供的IReconciler實現會在source viewer配置的過程中被install,那么,如果我們在我們自己的IReconciler install實現中做進一步的關聯實現不就可以了^_^ 例如,我們可以在自己的IReconciler install實現中,將自己注冊為當前IDocument(ITextViewer.getDocument)的document change listener,這樣當編輯器中的內容發生變化(IDocument發生改變)時候,我們就可以根據變化區域對應的內容類型去獲取相應的IReconcilingStrategy,并執行驗證了^_^
為了更好的說明這一點,我們看一下Eclipse中Java源碼編輯器是如何處理的:
public class JavaReconciler extends MonoReconciler {
/**
* Internal Java element changed listener
*
* @since 3.0
*/
private class ElementChangedListener implements IElementChangedListener {
/*
* @see org.eclipse.jdt.core.IElementChangedListener#elementChanged(org.eclipse.jdt.core.ElementChangedEvent)
*/
public void elementChanged(ElementChangedEvent event) {
if (event.getDelta().getFlags() == IJavaElementDelta.F_AST_AFFECTED)
return;
setJavaModelChanged(true);
if (!fIsReconciling && isEditorActive() )
JavaReconciler.this.forceReconciling();
}
}
/** The part listener */
private IPartListener fPartListener;
/** The shell listener */
private ShellListener fActivationListener;
/**
* The Java element changed listener.
* @since 3.0
*/
private IElementChangedListener fJavaElementChangedListener;
/**
* The resource change listener.
* @since 3.0
*/
private IResourceChangeListener fResourceChangeListener;
/*
* @see org.eclipse.jface.text.reconciler.IReconciler#install(org.eclipse.jface.text.ITextViewer)
*/
public void install(ITextViewer textViewer) {
super.install(textViewer);
fPartListener= new PartListener();
IWorkbenchPartSite site= fTextEditor.getSite();
IWorkbenchWindow window= site.getWorkbenchWindow();
window.getPartService().addPartListener(fPartListener);
fActivationListener= new ActivationListener(textViewer.getTextWidget());
Shell shell= window.getShell();
shell.addShellListener(fActivationListener);
fJavaElementChangedListener= new ElementChangedListener();
JavaCore.addElementChangedListener(fJavaElementChangedListener);
fResourceChangeListener= new ResourceChangeListener();
IWorkspace workspace= JavaPlugin.getWorkspace();
workspace.addResourceChangeListener(fResourceChangeListener);
}
//其他代碼省略
}
上面的JavaReconciler就是java源碼編輯器中source viwer使用的IReconciler實現,我們看到在其install的過程中,其實是注冊了相應的監聽器,當監聽到相應的變化時,就做相應的驗證處理就可以了^_^
IReconciler安裝和工作:

同樣,當對應的IEditorPart實例銷毀時,那么內含的source viewer肯定要銷毀,并執行unconfig操作,在unconfig的過程中,會調用相應IReconciler實現的uninstall操作。

PS:IReconciler.install中做了監聽器注冊等行為,別忘記在IReconciler.uninstall中做相應清理!!!
【WTP StructuredTextEditor源碼即時校驗實現分析】
我想通過上面JFace Text Framework中相應機制的分析,再回過頭來看WTP StructuredTextEditor中如何實現源碼校驗的,應該不是很難^_^。我們將重點關注兩點:1、對應的IReconciler實現;2、具體的IReconcilingStrategy實現;3、如何擴展?
前面我們已經定義了一個source viewer configuration,沿著繼承關系,我們找到了對應的IReconciler實現:
public class StructuredTextViewerConfiguration extends TextSourceViewerConfiguration {
final public IReconciler getReconciler(ISourceViewer sourceViewer) {
boolean reconcilingEnabled = fPreferenceStore.getBoolean(CommonEditorPreferenceNames.EVALUATE_TEMPORARY_PROBLEMS);
if (sourceViewer == null || !reconcilingEnabled)
return null;
/*
* Only create reconciler if sourceviewer is present
*/
if (fReconciler == null && sourceViewer != null) {
StructuredRegionProcessor reconciler = new StructuredRegionProcessor();
// reconciler configurations
reconciler.setDocumentPartitioning(getConfiguredDocumentPartitioning(sourceViewer));
fReconciler = reconciler;
}
return fReconciler;
}
}
上面紅色標志的
StructuredRegionProcessor(org.eclipse.wst.sse.ui.internal.reconcile.StructuredRegionProcessor)就是WTP提供的IReconciler接口的具體實現。繼承關系圖:

順藤摸瓜,我們找到了對應的IReconciler.install實現:
public class DirtyRegionProcessor extends Job implements IReconciler, IReconcilerExtension, IConfigurableReconciler {
class DocumentListener implements IDocumentListener {
//處理document change事件,執行即時校驗
}
class TextInputListener implements ITextInputListener {
public void inputDocumentAboutToBeChanged(IDocument oldInput, IDocument newInput) {
// do nothing
}
public void inputDocumentChanged(IDocument oldInput, IDocument newInput) {
handleInputDocumentChanged(oldInput, newInput);
}
}
/**
* @see org.eclipse.jface.text.reconciler.IReconciler#install(ITextViewer)
*/
public void install(ITextViewer textViewer) {
// we might be called multiple times with the same viewe.r,
// maybe after being uninstalled as well, so track separately
if (!isInstalled()) {
fViewer = textViewer;
fTextInputListener = new TextInputListener();
textViewer.addTextInputListener(fTextInputListener);
setInstalled(true);
}
}
/**
*
* @param oldInput
* @param newInput
*/
void handleInputDocumentChanged(IDocument oldInput, IDocument newInput) {
// don't bother if reconciler not installed
if (isInstalled()) {
reconcilerDocumentChanged(newInput);
setDocument(newInput);
setEntireDocumentDirty(newInput);
}
}
/**
* Reinitializes listeners and sets new document onall strategies.
*
* @see org.eclipse.jface.text.reconciler.AbstractReconciler#reconcilerDocumentChanged(IDocument)
*/
void reconcilerDocumentChanged(IDocument newDocument) {
IDocument currentDoc = getDocument();
// unhook old document listener
if (currentDoc != null)
currentDoc.removeDocumentListener(fDocumentListener);
// hook up new document listener
if (newDocument != null)
newDocument.addDocumentListener(fDocumentListener);
// sets document on all strategies
setDocument(newDocument);
}
//其他代碼省略...
}
我們看到,WTP提供的IReconciler實現在install的過程中,注冊了text input listener,當input變化的時候,則獲取和input對應的document,并針對該document注冊相應的document change listener,當document發生變化的時候(用戶即時編輯內容會造成這種變化),執行相應的驗證邏輯。
到這里我們先停一下,我們看到WTP提供的StructuredTextViewerConfiguration(也就是我們定義的viewer configuration的間接父類)對getReconciler方法做了final處理。既然我們自定義的viewer configuration間接繼承自StructuredTextViewerConfiguration,所以我們提供自定義的IReconciler實現的方式就走不通了哈^_^。那我們如何擴展呢?
我們看一下WTP提供的具體reconciling處理過程吧:
public class DocumentRegionProcessor extends DirtyRegionProcessor {
/**
* @param dirtyRegion
*/
protected void process(DirtyRegion dirtyRegion) {
if (!isInstalled())
return;
super.process(dirtyRegion);
// Also call the validation and spell-check strategies
ITypedRegion[] partitions = computePartitioning(dirtyRegion);
DirtyRegion dirty = null;
for (int i = 0; i < partitions.length; i++) {
// [source]validator (extension) for this partition
if (getValidatorStrategy() != null) {
dirty = createDirtyRegion(partitions[i], DirtyRegion.INSERT);
getValidatorStrategy().reconcile(partitions[i], dirty);
}
}
// single spell-check for everything
if (getSpellcheckStrategy() != null) {
getSpellcheckStrategy().reconcile(dirtyRegion, dirtyRegion);
}
}
protected ValidatorStrategy getValidatorStrategy() {
//收集擴展點org.eclipse.wst.sse.ui.sourcevalidation對應擴展
}
}
我們看到WTP并沒有,WTP提供了一個全能的IReconcilingStrategy實現(org.eclipse.wst.sse.ui.internal.reconcile.validator.ValidatorStrategy),這個IReconcilingStrategy實現定義了擴展點org.eclipse.wst.sse.ui.sourcevalidation來邀請用戶進行擴展,擴展的方式是:提供一個org.eclipse.wst.validation.internal.provisional.core.IValidator接口的實現,并和特定的分區類型(partition type)相關聯。ValidatorStrategy根據特定分區類型去調用對應的擴展功能,然后負責創建對應Annotation列表并放入編輯器對應的IAnnotationModel中去,用戶校驗邏輯提供的信息就可以再編輯器上顯示了,就像文章剛開頭我們看到的那張圖片一樣^_^。
PS:有關 Annotation(org.eclipse.jface.text.source.Annotation)和IAnnotationModel(org.eclipse.jface.text.source.IAnnotationModel)也是JFace Text Framework提供的特性,用于處理用戶對編輯器中文檔內容注釋信息的顯示。有關具體內容,有興趣的可以去看一下,后面有時間,我會再blog里面發一套有關JFace Text Framework關鍵特性分析和如何擴展的文章^_^。
我們回過頭來回顧一下WTP提供的reconciling實現吧:

不再接著分析下去了,有興趣的同學可以自己去看一下WTP中對應的更詳細地代碼實現。我們只要記住通過org.eclipse.wst.sse.ui.sourcevalidation來注冊自己的校驗邏輯就可以了。
【自定義標簽即時校驗實現摘要】
在上一節中我們提供了自動提示的擴展定制,針對的是屬性值提示。在本節,我們也主要是針對屬性值提示做一個示例,需求大致如下:
1、當用戶編輯標簽的屬性值時,對其做即時語義驗證,如果屬性值不合法,則顯示相應錯誤。
2、便于用戶擴展,需要提供相關擴展點,別的開發者可以針對特定標簽動態掛入校驗邏輯實現
【創建并注冊validator擴展】
根據前面的分析我們知道,想擴展WTP默認的即時源碼校驗,我們需要借助org.eclipse.wst.sse.ui.sourcevalidation擴展點動態掛入一個我們自己的IValidator實現。
public class JSPTagSourceValidator implements IValidator, ISourceValidator{
private IStructuredDocument document;
public void cleanup(IReporter reporter) {
// TODO Auto-generated method stub
}
public void validate(IValidationContext helper, IReporter reporter) throws ValidationException {
// TODO Auto-generated method stub
}
public void connect(IDocument document) {
this.document = (IStructuredDocument)document;
}
public void disconnect(IDocument document) {
// TODO Auto-generated method stub
}
public void validate(IRegion dirtyRegion, IValidationContext helper, IReporter reporter) {
IStructuredModel structuredModel = StructuredModelManager.getModelManager().getModelForRead(this.document);
if (structuredModel == null)
return ;
try {
IStructuredDocumentRegion[] structuredRegions = this.document.getStructuredDocumentRegions(dirtyRegion.getOffset(), dirtyRegion.getOffset());
for (int i = 0; i < structuredRegions.length; i++) {
//判斷是否是標簽
if (structuredRegions[i].getType() != DOMRegionContext.XML_TAG_NAME)
continue ;
IndexedRegion indexRegioned = structuredModel.getIndexedRegion(structuredRegions[i].getStartOffset());
if (!(indexRegioned instanceof IDOMElement))
continue ;
//執行標簽驗證,并設置信息
IDOMElement domElement = (IDOMElement)indexRegioned;
String tagName = domElement.getNodeName();
ITagValidator tagValidator = TagValidatorManager.getInstance().getTagValidator(tagName);
if (tagValidator != null) {
IMessage[] messages = tagValidator.validate(domElement, reporter);
for (int j = 0; j < messages.length; j++) {
reporter.addMessage(this, messages[i]);
}
}
}
} catch (Exception e) {
//log exception
IStatus status = new Status(IStatus.ERROR, "jspeditor", 1001, "校驗過程過程出錯", e);
Activator.getDefault().getLog().log(status);
} finally {
//重要:削減模型引用計數
if (structuredModel != null)
structuredModel.releaseFromRead();
}
}
}
上面代碼的細節我們先不看,ITagValidator接口使我們定義的,后面會看到。我們創建了自己的validator實現,分析變化region,如果所在標簽有對應的ITagValidator實現,就執行相應的驗證邏輯。我們的擴展是有了,下面就是將其動態掛入WTP了:
<extension
point="org.eclipse.wst.sse.ui.sourcevalidation">
<validator
scope="partial"
class="jspeditor.internal.sourcevalidation.JSPTagSourceValidator"
id="jspeditor.attrbuteValueValidator">
<contentTypeIdentifier
id="org.eclipse.jst.jsp.core.jspsource">
<partitionType id="org.eclipse.jst.jsp.JSP_DIRECTIVE"/>
</contentTypeIdentifier>
</validator>
</extension>
注意上面的partitionType,由于我們主要是執行JSP Tag的即時校驗,我們關注的分區類型自然就是org.eclipse.jst.jsp.JSP_DIRECTIVE。
PS:關于partiton type的詳細分析前面的章節中有,不清楚的可以取看一下。如果你自己的校驗器有其他的驗證需求,則搞清楚對應區域的分區類型應該是什么,然后添加到以上擴展的contentTypeIdentifier中,一個vaidator可以跟多個partition type相綁定。
【定義自己的標簽驗證擴展點】
分析需求可以發現,對于不同的標簽執行驗證,只是驗證的具體邏輯不同,抽象概念還是一個。又希望以后的開發者可以提供擴展,所以我們再次采用擴展點機制(這個上一節中定制自動提示是非常相似的^_^)。代碼結構基本上也是按照策略模式來吧(驗證算法封裝為對象)^_^
public interface ITagValidator {
/**
* @param domElement 待驗證標簽的doom element
* @param reporter
* @return 無信息,請返回IMessage[0]
*/
public IMessage[] validate(IDOMElement domElement, IReporter reporter);
}
對應的默認適配器類如下,主要兩個作用:1、提供一個算法估計骨架(template method^_^);2、封裝一些公共操作。
/**
* ITagValidator接口對應的default adapter類。
*
* @author zhuxing (mailto:zhu_xing@live.cn)
*/
/*
* 修改歷史
* $Log$
*/
public abstract class AbstractTagValidator implements ITagValidator {
/*
* 簡單示例算法流程:
* 1、執行標簽級別的驗證
* 2、執行屬性級別的驗證
*
* @see jspeditor.sourcevalidation.ITagValidator#validate(org.eclipse.wst.xml.core.internal.provisional.document.IDOMElement, org.eclipse.wst.validation.internal.provisional.core.IReporter)
*/
public IMessage[] validate(IDOMElement domElement, IReporter reporter) {
if (domElement == null)
return new IMessage[0];
List<IMessage> messages = new ArrayList<IMessage>();
//執行標簽級別驗證
Collections.addAll(messages, this.validateElement(domElement, reporter));
//執行屬性級別驗證
NamedNodeMap attributes = domElement.getAttributes();
if (attributes != null) {
for (int index = 0; index < attributes.getLength(); index++) {
IDOMAttr domAttr = (IDOMAttr)attributes.item(index);
Collections.addAll(messages, this.validateAttr(domAttr, reporter));
}
}
return messages.toArray(new IMessage[messages.size()]);
}
/**
* 執行element級別的驗證,例如可以執行標簽屬性是否完整、是否有多余屬性等
*
* @param domElement
* @param reporter
* @return 無信息,請返回IMessage[0]
*/
public abstract IMessage[] validateElement(IDOMElement domElement, IReporter reporter);
/**
* @param domAttr 執行attribute級別的驗證,例如驗證屬性值是否合法等
* @param reporter
* @return 無信息,請返回IMessage[0]
*/
public abstract IMessage[] validateAttr(IDOMAttr domAttr, IReporter reporter);
}
我們同樣為ITagValidator類型提供一個實例管理器(具體代碼請參見附件源碼下載鏈接),負責處理加載擴展細節,并提供一個接口允許客戶端以tag name獲取對應的ITagValidator實現。這個在上面的validator擴展類(JSPTagSourceValidator)上下文中已經使用,紅色加粗部分的代碼^_^
需求也分析了,變化也得到封裝了,那就看一下擴展點的定義吧:

我們的擴展點定義的很簡單:為指定tag id 配置一個ITagValidator實現^_^
【注冊ITagVaildator擴展并測試】
我們延用上一節中的<test:test>標簽,我們還記得里面定義了一個scope屬性,允許的屬性值是request或者是session。那我們就為其開發一個ITagValidator驗證擴展,如果scope的屬性值不是request或者session,則報錯^_^
public class TestTagValidator extends AbstractTagValidator {
private static final String ATTR_NAME_SCOPE = "scope";
/* (non-Javadoc)
* @see jspeditor.sourcevalidation.AbstractTagValidator#validateElement(org.eclipse.wst.xml.core.internal.provisional.document.IDOMElement, org.eclipse.wst.validation.internal.provisional.core.IReporter)
*/
public IMessage[] validateElement(IDOMElement domElement, IReporter reporter) {
return new IMessage[0];
}
/* (non-Javadoc)
* @see jspeditor.sourcevalidation.AbstractTagValidator#validateAttr(org.eclipse.wst.xml.core.internal.provisional.document.IDOMAttr, org.eclipse.wst.validation.internal.provisional.core.IReporter)
*/
public IMessage[] validateAttr(IDOMAttr domAttr, IReporter reporter) {
if (domAttr == null)
return new IMessage[0];
if (ATTR_NAME_SCOPE.equals(domAttr.getName())) {
if (!("session".equalsIgnoreCase(domAttr.getValue())) && !("request".equalsIgnoreCase(domAttr.getValue()))) {
String messageText = "scope屬性值錯誤,只能為session或者request";
IMessage message = TagValidatorHelper.createMessage(IMessage.HIGH_SEVERITY, messageText, domAttr);
return new IMessage[]{message};
}
}
return new IMessage[0];
}
}
為test:test標簽注冊驗證擴展:

效果演示:

當我們給scope輸入的屬性值不是request或者session時,即時報錯了^_^
【后記】
在這一節中,其實提供了一個基于編輯器的標簽驗證框架的縮影^_^
PS:如果沒有擴展需求,可以考慮重新設計擴展方式,將依賴于擴展點的動態掛入擴展方式修改為默認的靜態注入的方式。有關合理利用擴展點機制的問題,博客上又兩篇相關的隨筆:
【Eclipse插件開發】在什么情況下創建擴展點
【Eclipse插件開發】Eclipse中的擴展點機制存在的理由
【源碼下載】
即時校驗定制工程源碼
本博客中的所有文章、隨筆除了標題中含有引用或者轉載字樣的,其他均為原創。轉載請注明出處,謝謝!