You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by pi...@apache.org on 2005/09/12 23:22:49 UTC
svn commit: r280424 - in
/cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon:
components/validation/ components/validation/impl/
components/validation/jaxp/ components/validation/jing/ transformation/
Author: pier
Date: Mon Sep 12 14:22:39 2005
New Revision: 280424
URL: http://svn.apache.org/viewcvs?rev=280424&view=rev
Log:
Better JavaDOCs
Modified:
cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/Schema.java
cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/impl/AbstractSchemaParser.java
cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/impl/CachingValidator.java
cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/impl/ValidationResolver.java
cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/jaxp/JaxpInput.java
cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/jaxp/JaxpResolver.java
cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/jaxp/JaxpSchema.java
cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/jaxp/JaxpSchemaParser.java
cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/jing/JingSchema.java
cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/transformation/ValidatingTransformer.java
Modified: cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/Schema.java
URL: http://svn.apache.org/viewcvs/cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/Schema.java?rev=280424&r1=280423&r2=280424&view=diff
==============================================================================
--- cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/Schema.java (original)
+++ cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/Schema.java Mon Sep 12 14:22:39 2005
@@ -68,10 +68,9 @@
*
* @param handler an {@link ErrorHandler} to notify of validation errors.
* @return a <b>non-null</b> {@link ValidationHandler} instance.
- * @throws NullPointerException if the {@link ErrorHandler} was <b>null</b>.
* @throws SAXException if an error occurred creating the validation handler.
*/
public ValidationHandler createValidator(ErrorHandler handler)
- throws NullPointerException, SAXException;
+ throws SAXException;
}
Modified: cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/impl/AbstractSchemaParser.java
URL: http://svn.apache.org/viewcvs/cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/impl/AbstractSchemaParser.java?rev=280424&r1=280423&r2=280424&view=diff
==============================================================================
--- cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/impl/AbstractSchemaParser.java (original)
+++ cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/impl/AbstractSchemaParser.java Mon Sep 12 14:22:39 2005
@@ -49,6 +49,13 @@
protected Logger logger = null;
/**
+ * <p>Create a new {@link AbstractSchemaParser} instance.</p>
+ */
+ public AbstractSchemaParser() {
+ super();
+ }
+
+ /**
* <p>Enable logging.</p>
*/
public void enableLogging(Logger logger) {
Modified: cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/impl/CachingValidator.java
URL: http://svn.apache.org/viewcvs/cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/impl/CachingValidator.java?rev=280424&r1=280423&r2=280424&view=diff
==============================================================================
--- cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/impl/CachingValidator.java (original)
+++ cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/impl/CachingValidator.java Mon Sep 12 14:22:39 2005
@@ -40,6 +40,13 @@
private Store store = null;
/**
+ * <p>Create a new {@link CachingValidator} instance.</p>
+ */
+ public CachingValidator() {
+ super();
+ }
+
+ /**
* <p>Initialize this component instance.</p>
*/
public void initialize()
Modified: cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/impl/ValidationResolver.java
URL: http://svn.apache.org/viewcvs/cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/impl/ValidationResolver.java?rev=280424&r1=280423&r2=280424&view=diff
==============================================================================
--- cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/impl/ValidationResolver.java (original)
+++ cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/impl/ValidationResolver.java Mon Sep 12 14:22:39 2005
@@ -164,7 +164,7 @@
}
/**
- * <p>Close this {@link ValidatorResolver} instance, releasing all created
+ * <p>Close this {@link ValidationResolver} instance, releasing all created
* {@link Source}s back to the {@link SourceResolver} and returning an
* aggregated {@link SourceValidity}.</p>
*/
Modified: cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/jaxp/JaxpInput.java
URL: http://svn.apache.org/viewcvs/cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/jaxp/JaxpInput.java?rev=280424&r1=280423&r2=280424&view=diff
==============================================================================
--- cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/jaxp/JaxpInput.java (original)
+++ cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/jaxp/JaxpInput.java Mon Sep 12 14:22:39 2005
@@ -21,13 +21,29 @@
import org.w3c.dom.ls.LSInput;
import org.xml.sax.InputSource;
-final class JaxpInput implements LSInput {
-
+/**
+ * <p>An implementation of the {@link LSInput} interface wrapping a nested
+ * {@link InputSource}.</p>
+ *
+ * @author <a href="mailto:pier@betaversion.org">Pier Fumagalli</a>
+ */
+public class JaxpInput implements LSInput {
+
+ /** <p>The wrapped {@link InputSource} instance.</p> */
private final InputSource input;
+ /** <p>The flag to return by the {@link #getCertifiedText()} method.</p> */
private boolean cert = false;
+ /** <p>A string wrapping the data to parse.</p> */
private String data = null;
+ /** <p>The optional base URI for relative resolution.</p> */
private String base = null;
+ /**
+ * <p>Create a new {@link JaxpInput} instance.</p>
+ *
+ * @param input a <b>non-null</b> {@link InputSource} instance to wrap.
+ * @throws NullPointerException if the {@link InputSource} was <b>null</b>.
+ */
public JaxpInput(InputSource input) {
if (input == null) throw new NullPointerException("Null InputSource");
this.input = input;
Modified: cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/jaxp/JaxpResolver.java
URL: http://svn.apache.org/viewcvs/cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/jaxp/JaxpResolver.java?rev=280424&r1=280423&r2=280424&view=diff
==============================================================================
--- cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/jaxp/JaxpResolver.java (original)
+++ cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/jaxp/JaxpResolver.java Mon Sep 12 14:22:39 2005
@@ -15,7 +15,6 @@
*/
package org.apache.cocoon.components.validation.jaxp;
-
import org.apache.cocoon.components.validation.impl.ValidationResolver;
import org.apache.excalibur.source.SourceResolver;
import org.w3c.dom.DOMError;
@@ -25,16 +24,42 @@
import org.xml.sax.EntityResolver;
import org.xml.sax.InputSource;
+/**
+ * <p>An implementation of the {@link LSResourceResolver} interface based on the
+ * generic {@link ValidationResolver} to supply to JAXP schema factories.</p>
+ *
+ * @author <a href="mailto:pier@betaversion.org">Pier Fumagalli</a>
+ */
public class JaxpResolver extends ValidationResolver
implements LSResourceResolver {
-
+
+ /**
+ * <p>Create a new {@link JaxpResolver} instance.</p>
+ */
public JaxpResolver(SourceResolver sourceResolver,
EntityResolver entityResolver) {
super(sourceResolver, entityResolver);
}
+ /**
+ * <p>Resolve a resource into a {@link LSInput} from the provided location
+ * information.</p>
+ *
+ * <p>This method will obtain a {@link InputSource} instance invoking the
+ * {@link ValidationResolver#resolveEntity(String, String, String)} method
+ * return it wrapped in a {@link JaxpInput} instance.</p>
+ *
+ * @param type the type of the resource being resolved.
+ * @param namespace the namespace of the resource being resolved.
+ * @param systemId the system identifier of the resource being resolved.
+ * @param publicId the public identifier of the resource being resolved.
+ * @param base the base uri against wich relative resolution should happen.
+ * @return a <b>non null</b> {@link LSInput} instance.
+ * @throws LSException wrapping another {@link Exception}.
+ */
public LSInput resolveResource(String type, String namespace, String systemId,
- String publicId, String base) {
+ String publicId, String base)
+ throws LSException {
try {
final InputSource source = this.resolveEntity(base, publicId, systemId);
return new JaxpInput(source);
Modified: cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/jaxp/JaxpSchema.java
URL: http://svn.apache.org/viewcvs/cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/jaxp/JaxpSchema.java?rev=280424&r1=280423&r2=280424&view=diff
==============================================================================
--- cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/jaxp/JaxpSchema.java (original)
+++ cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/jaxp/JaxpSchema.java Mon Sep 12 14:22:39 2005
@@ -21,29 +21,54 @@
import org.apache.cocoon.components.validation.ValidationHandler;
import org.apache.cocoon.components.validation.impl.AbstractSchema;
import org.apache.cocoon.components.validation.impl.DefaultValidationHandler;
+import org.apache.cocoon.components.validation.impl.DraconianErrorHandler;
import org.apache.excalibur.source.SourceValidity;
import org.xml.sax.ErrorHandler;
import org.xml.sax.SAXException;
/**
- * <p>TODO: ...</p>
+ * <p>An extension of the {@link AbstractSchema} class specific to the
+ * {@link JaxpSchemaParser} implementation.</p>
*
* @author <a href="mailto:pier@betaversion.org">Pier Fumagalli</a>
*/
public class JaxpSchema extends AbstractSchema {
-
+
+ /** <p>The wrapped JAXP {@link Schema} instance.</p> */
private final Schema schema;
-
+
+ /**
+ * <p>Create a new {@link JaxpSchema} instance.</p>
+ *
+ * @param schema the {@link Schema} instance to wrap.
+ * @param validity the {@link SourceValidity} associated with the schema.
+ */
public JaxpSchema(Schema schema, SourceValidity validity) {
super(validity);
this.schema = schema;
}
+ /**
+ * <p>Return a new {@link ValidationHandler} instance that can be used to
+ * validate an XML document by sending SAX events to it.</p>
+ *
+ * <p>The specified {@link ErrorHandler} will be notified of all warnings or
+ * errors encountered validating the SAX events sent to the returned
+ * {@link ValidationHandler}, and <b>must not</b> be <b>null</b>.</p>
+ *
+ * <p>The returned {@link ValidationHandler} can be used to validate <b>only
+ * one</b> XML document. To validate more than one document, this method should
+ * be called once for each document to validate.</p>
+ *
+ * @param handler an {@link ErrorHandler} to notify of validation errors.
+ * @return a <b>non-null</b> {@link ValidationHandler} instance.
+ * @throws SAXException if an error occurred creating the validation handler.
+ */
public ValidationHandler createValidator(ErrorHandler handler)
- throws NullPointerException, SAXException {
+ throws SAXException {
+ if (handler == null) handler = DraconianErrorHandler.INSTANCE;
ValidatorHandler validator = this.schema.newValidatorHandler();
validator.setErrorHandler(handler);
return new DefaultValidationHandler(this.getValidity(), validator);
}
-
}
Modified: cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/jaxp/JaxpSchemaParser.java
URL: http://svn.apache.org/viewcvs/cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/jaxp/JaxpSchemaParser.java?rev=280424&r1=280423&r2=280424&view=diff
==============================================================================
--- cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/jaxp/JaxpSchemaParser.java (original)
+++ cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/jaxp/JaxpSchemaParser.java Mon Sep 12 14:22:39 2005
@@ -28,23 +28,59 @@
import org.apache.avalon.framework.configuration.ConfigurationException;
import org.apache.avalon.framework.thread.ThreadSafe;
import org.apache.cocoon.components.validation.Schema;
+import org.apache.cocoon.components.validation.SchemaParser;
import org.apache.cocoon.components.validation.Validator;
import org.apache.cocoon.components.validation.impl.AbstractSchemaParser;
import org.apache.cocoon.components.validation.impl.DraconianErrorHandler;
import org.apache.excalibur.source.Source;
+import org.xml.sax.ErrorHandler;
import org.xml.sax.SAXException;
/**
- * <p>TODO: ...</p>
+ * <p>An implementation of the {@link SchemaParser} interface wrapping JAXP
+ * {@link SchemaFactory} instances.</p>
*
* @author <a href="mailto:pier@betaversion.org">Pier Fumagalli</a>
*/
public class JaxpSchemaParser extends AbstractSchemaParser
implements Configurable, ThreadSafe {
+ /** <p>The class name of the {@link SchemaFactory} to use.</p> */
private String className = null;
+ /** <p>The list of grammars supported by this instance.</p> */
private String[] grammars = null;
+ /**
+ * <p>Create a new {@link JaxpSchemaParser} instance.</p>
+ */
+ public JaxpSchemaParser() {
+ super();
+ }
+
+ /**
+ * <p>Configure this instance.</p>
+ *
+ * <p>The {@link JaxpSchemaParser} requires at least one configuration element:
+ * <code><factory-class><i>class name</i></factory-class></code>.
+ * This specifies the JAXP {@link SchemaFactory} class to be used by this
+ * instance.</p>
+ *
+ * <p>Grammars will be automatically detected if the {@link SchemaFactory}
+ * supports one of the {@link XMLConstants#RELAXNG_NS_URI RELAX-NG} grammar,
+ * {@link XMLConstants#W3C_XML_SCHEMA_NS_URI XML-Schema} grammar, or the
+ * {@link XMLConstants#XML_DTD_NS_URI XML-DTD} grammar.</p>
+ *
+ * <p>If the factory is known to support different grammars, the default
+ * detection can be overridden specifying in the configuration something similar
+ * to the following:</p>
+ *
+ * <pre>
+ * <grammars>
+ * <grammar>... a first grammar identifier ...</grammar>
+ * <grammar>... another grammar identifier ...</grammar>
+ * </grammars>
+ * </pre>
+ */
public void configure(Configuration conf)
throws ConfigurationException {
this.className = conf.getChild("factory-class").getValue();
@@ -91,6 +127,20 @@
this.grammars = (String[]) grammars.toArray(new String[grammars.size()]);
}
+ /**
+ * <p>Parse the specified {@link Source} and return a new {@link Schema}.</p>
+ *
+ * <p>The returned {@link Schema} must be able to validate multiple documents
+ * via multiple invocations of {@link Schema#createValidator(ErrorHandler)}.</p>
+ *
+ * @param source the {@link Source} associated with the {@link Schema} to return.
+ * @return a <b>non-null</b> {@link Schema} instance.
+ * @throws SAXException if a grammar error occurred parsing the schema.
+ * @throws IOException if an I/O error occurred parsing the schema.
+ * @throws IllegalArgumentException if the specified grammar type is not one
+ * of the grammar types returned by the
+ * {@link #getSupportedGrammars()} method.
+ */
public Schema parseSchema(Source source, String grammar)
throws SAXException, IOException {
final SchemaFactory factory;
Modified: cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/jing/JingSchema.java
URL: http://svn.apache.org/viewcvs/cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/jing/JingSchema.java?rev=280424&r1=280423&r2=280424&view=diff
==============================================================================
--- cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/jing/JingSchema.java (original)
+++ cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/components/validation/jing/JingSchema.java Mon Sep 12 14:22:39 2005
@@ -18,6 +18,7 @@
import org.apache.cocoon.components.validation.ValidationHandler;
import org.apache.cocoon.components.validation.impl.AbstractSchema;
import org.apache.cocoon.components.validation.impl.DefaultValidationHandler;
+import org.apache.cocoon.components.validation.impl.DraconianErrorHandler;
import org.apache.excalibur.source.SourceValidity;
import org.xml.sax.ContentHandler;
import org.xml.sax.ErrorHandler;
@@ -28,7 +29,6 @@
import com.thaiopensource.validate.Schema;
import com.thaiopensource.validate.ValidateProperty;
import com.thaiopensource.validate.Validator;
-import com.thaiopensource.xml.sax.DraconianErrorHandler;
/**
* <p>An extension of {@link AbstractSchema} used by the {@link JingSchemaParser}
@@ -60,15 +60,13 @@
* errors encountered validating the SAX events sent to the returned
* {@link ValidationHandler}.</p>
*
- * <p>Once used, the returned {@link ValidationHandler} <b>can't</b> be reused.</p>
- *
* @param errorHandler an {@link ErrorHandler} to notify of validation errors.
* @return a <b>non-null</b> {@link ValidationHandler} instance.
* @throws SAXException if an error occurred creating the validation handler.
*/
public ValidationHandler createValidator(ErrorHandler errorHandler)
throws SAXException {
- if (errorHandler == null) errorHandler = new DraconianErrorHandler();
+ if (errorHandler == null) errorHandler = DraconianErrorHandler.INSTANCE;
final PropertyMapBuilder builder = new PropertyMapBuilder();
ValidateProperty.ERROR_HANDLER.put(builder, errorHandler);
final PropertyMap properties = builder.toPropertyMap();
Modified: cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/transformation/ValidatingTransformer.java
URL: http://svn.apache.org/viewcvs/cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/transformation/ValidatingTransformer.java?rev=280424&r1=280423&r2=280424&view=diff
==============================================================================
--- cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/transformation/ValidatingTransformer.java (original)
+++ cocoon/branches/BRANCH_2_1_X/src/blocks/validation/java/org/apache/cocoon/transformation/ValidatingTransformer.java Mon Sep 12 14:22:39 2005
@@ -60,12 +60,24 @@
public class ValidatingTransformer extends AbstractTransformer
implements Configurable, Serviceable, Disposable, CacheableProcessingComponent {
+ /** <p>The configured {@link ServiceManager} instance.</p> */
private ServiceManager serviceManager = null;
+ /** <p>The configured {@link Validator} instance.</p> */
private Validator validator = null;
+ /** <p>The configured default grammar language.</p> */
private String grammar = null;
+ /** <p>The {@link ValidationHandler} to use in this transformation.</p> */
private ValidationHandler handler = null;
+ /** <p>A unique key identifying the schema source for caching.</p> */
private String key = null;
+
+ /**
+ * <p>Create a new {@link ValidatingTransformer} instance.</p>
+ */
+ public ValidatingTransformer() {
+ super();
+ }
/**
* <p>Contextualize this component instance specifying its associated