dev doc updates
diff --git a/plugins/org.eclipse.jst.jsf.doc.dev/html/extpts_reference/index.html b/plugins/org.eclipse.jst.jsf.doc.dev/html/extpts_reference/index.html index be3f40d..c8a5644 100644 --- a/plugins/org.eclipse.jst.jsf.doc.dev/html/extpts_reference/index.html +++ b/plugins/org.eclipse.jst.jsf.doc.dev/html/extpts_reference/index.html
@@ -3,7 +3,7 @@ <html xmlns:xalan="http://xml.apache.org/xslt"> <head> <META http-equiv="Content-Type" content="text/html; charset=UTF-8"> - <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." > + <meta name="copyright" content="Copyright (c) Oracle Corporation and others 2006. This page is made available under EPL license." > <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <title>WTP JavaServer Faces Tools (JSF) Extension Points</title> @@ -46,6 +46,9 @@ <a href="jsf/org_eclipse_jst_jsf_facesconfig_common_overviewPage.html">org.eclipse.jst.jsf.facesconfig.common.overviewPage</a> </li> <li> +<a href="jsf/org_eclipse_jst_jsf_metadataprocessors_AttributeValueRuntimeTypes.html">org.eclipse.jst.jsf.metadataprocessors.AttributeValueRuntimeTypes</a> +</li> +<li> <a href="jsf/org_eclipse_jst_jsf_metadataprocessors_MetaDataEnabledFeatures.html">org.eclipse.jst.jsf.metadataprocessors.MetaDataEnabledFeatures</a> </li> </ul>
diff --git a/plugins/org.eclipse.jst.jsf.doc.dev/html/programmersguide/annotations_framework.html b/plugins/org.eclipse.jst.jsf.doc.dev/html/programmersguide/annotations_framework.html index ed79741..df7b468 100644 --- a/plugins/org.eclipse.jst.jsf.doc.dev/html/programmersguide/annotations_framework.html +++ b/plugins/org.eclipse.jst.jsf.doc.dev/html/programmersguide/annotations_framework.html
@@ -3,13 +3,16 @@ <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <link rel="stylesheet" href="../../book.css" type="text/css"/> +<link rel="stylesheet" href="../tutorials/default_style.css"/> <title>Content Model Annotations Framework</title> </head> <body> <h1>Content Model Annotations Framework</h1> <br> +<h3>Overview</h3> <p>The purpose of the JSF content model annotations framework is to provide a mechanism by which Eclipse plugin developers can attach the required meta-data to support improved tooling for XML content models. XML Content models (DTD, Schema, Taglibs), do not contain all of the information that is required to provide high-quality tooling support. The information that they contain simply does not have all of the information to provide semantic validation, content assistance, graphical tooling support, etc. This framework is the foundation for providing meta-data driven features used with the JSF JSP source editor in this release.</p> <p>A content model can have any number of annotations files associated with it. The public id of the content model is the key. eg. "http://java.sun.com/jsf/core"</p> +<h3>Extension Point</h3> <p>The annotation file uses the extension-point <code>org.eclipse.jst.jsf.contentmodel.annotations.annotationFiles</code> to attach itself to the uri identifier of the content model.</p> <p>Through the extension-point:</p> <ul> @@ -19,7 +22,7 @@ </ul> <p>An annotation file has named properties with one or more values that are given to xml elements and attributes. The file can associate 0-N named properties with any element or attribute. If there is more than one annotation file associated with the same public id and element/attribute, and there is a like-named property, it is not deterministic which property will be returned. The caller could, however, use the bundle ID of where the annotation file was created. A single plugin should not supply more than one annotation file for a given content model so that an annotation file can be identifiable. </p> <h6>eg. A Section of the JSF Core Taglibrary Annotation File</h6> -<pre> +<div class="code"><pre> <cm-element name="actionListener"> <cm-attribute name="type"> <property name="attribute-value-runtime-type"> @@ -53,8 +56,8 @@ etc.... </cm-element> etc.... -</pre> - +</pre></div> +<h3>Accessing Annotations</h3> <p>Annotations should only be accessed thru static calls to the <code>CMAnnotationHelper</code> class. This class has many convenience methods for accessing annotations on elements and attributes. Generally, lists of CMAnnotationPropertyValues are returned for a given property name on a particular element or attribute of an element. The CMAnnotationPropertyValues class allows the caller to know where the annotation came from which allows the caller some flexibility with using or not using the meta-data.</p> <p>Annotation files can be developed using wild cards to mimimize the amount of metadata that must be provided. These wild cards are supported in the sense that the caller can choose to request something other than the actual name of an element or attribute. So for example, if the attribute named "foo" applies to all elements in a content model, if "*" is used as the element name, the call to the <code>CMAnnotationHelper</code> can first look for "foo" attribute of the specifically named element, and if not found can look for the "foo" attribute on the "*" element in a second call. This gives the annotation provider greater flexibility in determining how the annotation files are structured and used. <i>The helper will not automatically locate wild-carded annotations.</i></p> <p>If no annotations are found by the call to <code>CMAnnotationHelper</code> for the passed parameters, methods that return:</p> @@ -62,6 +65,6 @@ <li><code>List</code> will return an empty list and not <code>null</code> </li> <li><code>String</code> will return <code>null</code></li> </ul> -<p>For more complete information on annotations files, please see the Annotations Design Summary in CVS at /home/webtools/org.eclipse.jsf/components/jsf/developement/design .</p> +<p>For more complete information on annotations files, please see the Annotations Design Summary in CVS at /home/webtools/org.eclipse.jsf/components/jsf/developement/design/metadata .</p> </body> </html> \ No newline at end of file
diff --git a/plugins/org.eclipse.jst.jsf.doc.dev/html/programmersguide/metadata_processing_framework.html b/plugins/org.eclipse.jst.jsf.doc.dev/html/programmersguide/metadata_processing_framework.html index dfff8f5..ad3774e 100644 --- a/plugins/org.eclipse.jst.jsf.doc.dev/html/programmersguide/metadata_processing_framework.html +++ b/plugins/org.eclipse.jst.jsf.doc.dev/html/programmersguide/metadata_processing_framework.html
@@ -3,11 +3,76 @@ <head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> <link rel="stylesheet" href="../../book.css" type="text/css"/> +<link rel="stylesheet" href="../tutorials/default_style.css"/> <title>Meta-Data Processing Framework</title> </head> <body> <h1>Meta-Data Processing Framework</h1> <br> -<p>CONTENT</p> +<h3>Overview</h3> +<p>This framework makes use of the meta-data contributed by the content model annotations framework. It's intention in this release is to simplify how servcies such as Content Assist and Validation can be provided in source editors for tag library based attributes values.</p> +<p>The goal for this framework is to allow developers to assign "runtime type" information to an attibute's value using annotations and then, because based on that type, "features" can naturally be exposed.</p> +<p>To make this more concrete, let's consider the example of the JSF Core <code>actionListener</code> tag and its <code>type</code> attribute. The value should resolve to a Java class type that implements the interface <code>javax.faces.event.ActionListener</code>. Having this knowledge is enough to provide:</p> +<ul> +<li>Validation - ensure that the specified class can be found and implements the correct interface</li> +<li>Content Assist - provide a list of all of the classes that can be found that implement the interface</li> +<li>Quick Fix/Quick Assist - open the new Java class wizard with the required interface preset in the dialog</li> +</ul> +<h3>Types and Features</h3> +<p>In the above example, the "Type" is a Java class type and we have identified three "Feature" that the type implements.<p> +<p>We have created an interface called <code><a href="../api_reference/org/eclipse/jst/jsf/metadataprocessors/internal/provisional/ITypeDescriptor.html">ITypeDescriptor</a></code> that represents the runtime type of the attribute value of a tag. An implementor needs to return a list of feature adapters that this type supports. The features must implement the <code><a href="../api_reference/org/eclipse/jst/jsf/metadataprocessors/internal/provisional/IMetaDataEnabledFeature.html">IMetaDataEnabledFeature</a></code> interface.</p> +<p>A default implementation, <code><a href="../api_reference/org/eclipse/jst/jsf/metadataprocessors/internal/provisional/AbstractRootTypeDescriptor.html">AbstractRootTypeDescriptor</a></code> has been provided as a convenient starting point for implementing types and it itself implements <code><a href="../api_reference/org/eclipse/jst/jsf/metadataprocessors/internal/provisional/AbstractMetaDataEnabledFeature.html">AbstractMetaDataEnabledFeature</a></code>. This allows the type descriptor to implement features itself which simplifies development.</p> +<h3>Attribute Value Runtime Type Extension Point</h3> +<p>We bind a type identifier in meta-data to a class through an extension point. <code><a href="../extpts_reference/jsf/org_eclipse_jst_jsf_metadataprocessors_AttributeValueRuntimeTypes.html">org.eclipse.jst.jsf.metadataprocessing.AttributeValueRuntimeTypes</a></code>. Please see <a href="./annotations_framework.html">content model annotations</a> extension-point to see how the annotations file is created.</p> +<p>The JSF Tools project has implemented a type descriptor class <code>org.eclipse.jst.jsf.taglibprocessing.internal.provisional.attributevalues.JavaClassType</code>. In order to use this type, it must first be declared as an <code>AttributeValueRuntimeTypes</code> and then refernced in an annotation file.</p> +<p>Below comes from the <code>org.eclipse.jst.jsf.taglibprocessing</code> plugin that declares this type:</p> +<div class="code"><pre> + <attributeValueRuntimeType + class="org.eclipse.jst.jsf.taglibprocessing.internal.provisional.attributevalues.JavaClassType" + id="attributevalues.JavaClassType"/> +</pre></div> +<p>Below is the section of the jsf_core.xml annotation file from the taglibprocessing plugin that annotates the <code>actionListener</code> tag:</p> +<div class="code"><pre> + <cm-element name="actionListener"> + <cm-attribute name="type"> + <property name="attribute-value-runtime-type"> + <value> + org.eclipse.jst.jsf.taglibprocessing.attributevalues.JavaClassType + </value> + </property> + <property name="valid-interfaces"> + <value>javax.faces.event.ActionListener</value> + </property> + </cm-attribute> + </cm-element> +</pre></div> +<p>Notice that the value of the property named <code>attribute-value-runtime-type</code> uses the plugin qualified id of the AttributeValueRuntimeType extension. This the property name of the annotation that associates the type identifier with the content model attribute.</p> +<p>For a complete list of implemented types and features, please see the <a href="../api_reference/org/eclipse/jst/jsf/taglibprocessing/internal/provisional/attributevalues/package-summary.html">API reference</a> +<p>The <code>JavaClassType</code> implements two Features:</p> +<ul> +<li><a href="../api_reference/org/eclipse/jst/jsf/metadataprocessors/internal/provisional/features/IValidValues.html">IValidValues</a> - an interface used by a WTP Validation framework validator class to check and provide validation error messages if invalid when being used in a non-EL context</li> +<li><a href="../api_reference/org/eclipse/jst/jsf/metadataprocessors/internal/provisional/features/IPossibleValues.html">IPossibleValues</a> - an interface used by an extension to the WTP SSE editor for content assistance</li> +</ul> +<p>Although not applicable to the <code>JavaClassType</code>, the following round out the Features defined by this release:</p> +<ul> +<li><a href="../api_reference/org/eclipse/jst/jsf/metadataprocessors/internal/provisional/features/IValidELValues.html">IValidELValues</a> - an interface used by a WTP Validation framework validator class to check and provide validation error messages if invalid when being used in an EL context</li> +<li><a href="../api_reference/org/eclipse/jst/jsf/metadataprocessors/internal/provisional/features/IDefaultValue.html">IDefaultValue</a> - an interface for providing a default value</li> +<li><a href="../api_reference/org/eclipse/jst/jsf/metadataprocessors/internal/provisional/features/ICreateValues.html">ICreateValues</a> - an unimplemented experimental interface with intentoin of being used for providing Quick Fix/Quick Assist services</li> +</ul> +<p>The Feature implementer can require additional information from the annotation. Notice that the <code>JavaClassType</code> gets the list of <code>valid-interface</code> values from the meta-data. For a complete list of the property names used by the Types and Features from the taglibprocessing plugin see the <a href="../api_reference/constant-values.html" >constant values reference page</a></p> +<h3>How are these used?</h3> +<p>A client interested in requesting a set of all the Feature implementers for a given tag attribute will use the <code><a href="../api_reference/org/eclipse/jst/jsf/metadataprocessors/internal/provisional/MetaDataEnabledProcessingFactory.html">MetaDataEnabledProcessingFactory</a> and the <code>getAttributeValueRuntimeTypeFeatureProcessors</code> method.</code>. +This method will lookup the runtime type from the annotations file that it will identify from the passed context. +This method is currently being called by the <code>JSPSemanticValidator</code> with <code>IValidValues.class</code> and <code>IValidELValues.class</code> passed as the feature class along with the context. For content assist, <code>IPossibleValues.class</code> is being passed by the content assist processor.</p> +<p>A content model can be annotated by multiple plugins. This means that for a given attribute, there may be multiple runtime type assigned to it each implementing the same or different features. In other words, the caller could get back a list of multiple feature implementers from different plugins. +The <code><a href="../api_reference/org/eclipse/jst/jsf/metadataprocessors/internal/provisional/CMAnnotationContext">CMAnnotationContext</a></code> returned with <code>IMetaDataEnabledFeature</code> could be useful in determining whether or not to use that feature. Generally, as is the case with the JSF content assist processor, this behaviour is "additive". All the features will be used which may result in multiple identical values appearing in the content assist popup menu. Currently there is no capabilty to "disable" Features to avoid this situation. It is presumed in the design that in most cases, only one plugin will provide annotations for a given content model.</p> +<h3>Creating New Behaviors</h3> +<p>Hopefully by now you know enough to create your own types, or reuse existing types in your annotation files. But what if you wanted to associate a completely new behaviour(Feature) with a runtime type? This is handled by implementing a new <code>IMetaDataEnabledFeature</code> and registering it against a type identifier. +To register, use the <code><a href="../extpts_reference/jsf/org_eclipse_jst_jsf_metadataprocessors_MetaDataEnabledFeatures.html">org.eclipse.jst.jsf.metadataprocessing.MetaDataEnabledFeatures</a></code> extension point. </p> +<h3>Other Resources</h3> +<ul> +<li>For more complete information on the metadata processing framework, please see the MetaDataFrameworksSummary in CVS at /home/webtools/org.eclipse.jsf/components/jsf/developement/design/metadata .</li> +<li><a href="../tutorials/supplying_tag_library_metadata_for_apache_myfaces_tomahawk.html">Tutorial</a></li> +</ul> </body> </html> \ No newline at end of file