MSV Core 2022.7 · com.sun.msv.verifier.Acceptor

exposes the low-level validation engine interface.

represents a pseudo-automaton acceptor. this interface is used to validate content models.

Perform Validation

To perform validation, call the createAcceptor method of the DocumentDeclaration interface to obtain an Acceptor for validating the document element.

Acceptor a = vgm.createAcceptor();

One acceptor is responsible for validating one element. So you also need some form of stack. If you are using a "push" interface like SAX, you need an explicit stack. If you are validating in "pull" fashion (like DOM), then you can use a recursion instead of an explicit stack. The following explanation assumes SAX-like interface.

Now, get back to the story. Whenever you encounter a start tag, create a new acceptor, which validates the children of newly encountered element.

stack.push(a);
a = a.createChildAcceptor( sti, null );

If this tag name was unexpected, then this method returns null. See javadoc for more details.

Then, for every attributes, call the onAttribute method. After that you call the onEndAttributes method.

for( int i=0; i<atts.getLength(); i++ )
  a.onAttribute( atts.getURI(i), .... );
a.onEndAttributes();

An error can occur at any method. See the method documentations for details.

If you find an end tag, make sure that the acceptor is satisfied. An acceptor is said to be unsatisfied when it needs more elements/text to complete the content model. For example, if the content model is (A,B,C) and it only sees (A,B), then the acceptor is not satisfied because it needs to see C.

if(!a.isAcceptState(null))
  ; // error because the acceptor is unsatisfied.
Acceptor child = a;
a = stack.pop();
a.stepForward(child,null);

Then, call the stepForward method of the parent acceptor and pass the child acceptor to it.

Finally, whenever you see a text, call the onText method. If the text was unexpected or not allowed, then this method returns null. See the documentation for details.

a.onText("text",context,null,null);

In this way, you can better control the validation process.

If you need even finer control of the validation process (e.g., you need to know the list of allowed elements/attributes), you may want to rely on the regexp implementation of VGM. see com.sun.msv.verifier.regexp.REDocumentDeclaration for detail.

Downcasting

It is often useful to downcast the Acceptor interface to appropriate derived class. For example, if you are using com.sun.msv.verifier.regexp.REDocumentDeclaration, then you can always downcast an Acceptor to com.sun.msv.verifier.regexp.ExpressionAcceptor, which provides more predictable behaviors and some useful methods.

Field Summary

Modifier and Type	Field and Description
public static final int	STRING_IGNORE character literals are allowed, but Acceptor doesn't care its contents and where it is appeared.
public static final int	STRING_PROHIBITED only whitespaces are allowed.
public static final int	STRING_STRICT attentive handling of characters is required.

Method Summary

Modifier and Type	Method and Description
public Acceptor	Returns: null If refErr is null, return null if the given start tag is not accepted. If refErr is non-null, return null only when the recovery is impossible. createChildAcceptor(StartTagInfo this parameter provides the information about the start tag to the acceptor object. Usually attribute information is ignored, but sometimes they are used as hints. sti, StringRef if this parameter is non-null, the implementation should try to detect the reason of error and recover from it. and this object should have the error message as its str field. refErr) creates an Acceptor that will accept the content model of the children of this moment.
public Acceptor	createClone() clones this acceptor.
public Object	Returns: null the callee should return null when it doesn't support type-assignment feature, or type-assignment is impossible for this acceptor (for example by ambiguous grammar). getOwnerType() gets the "type" object for which this acceptor is working.
public int	Returns: one of the three constant values shown below. getStringCareLevel() gets how this acceptor handles characters.
public boolean	isAcceptState(StringRef If this value is non-null, implementation can diagnose the error and sets the message to the object. errRef) checks if this Acceptor is satisifed.
public boolean	onAttribute(String namespaceURI, String localName, String qName, String value, IDContextProvider context, StringRef refErr, DatatypeRef refType) Deprecated
public boolean	Returns: false if an error happens and refErr parameter was not provided. Otherwise true. onAttribute2(String namespaceURI, String localName, String qName, String value, IDContextProvider2 context, StringRef In case of an error, this object will receive the localized error message. Null is a valid value for this parameter. The implementation must provide some kind of message. refErr, DatatypeRef If this parameter is non-null, this object will receive the datatype assigned to the attribute value. This feature is optional and therefore the implementation is not necessarily provide this information. refType) processes an attribute.
public boolean	Returns: false if an error happens and refErr parameter was not provided. Otherwise true. onEndAttributes(StartTagInfo This information is used to produce the error message if that is necessary. sti, StringRef In case of an error, this object will receive the localized error message. Null is a valid value for this parameter. The implementation must provide some kind of message. refErr) notifies the end of attributes.
public boolean	onText(String literal, IDContextProvider context, StringRef refErr, DatatypeRef refType) Deprecated
public boolean	Returns: false if the literal at this position is not allowed. onText2(String literal, IDContextProvider2 an object that provides context information necessary to validate some datatypes. context, StringRef if this parameter is non-null, the implementation should try to detect the reason of error and recover from it. and this object should have the error message as its str field. refErr, DatatypeRef if this parameter is non-null and the callee supports type-assignment, the callee will assign the DataType object to this variable. Caller must initialize refType.type to null before calling this method. If the callee doesn't support type-assignment or type-assignment is impossible for this literal (possibly by ambiguous grammar), this variable must kept null. refType) processes a string literal.
public boolean	Returns: false if an error happens. For example, if the implementation passes an acceptor which is NOT a child of this acceptor, then the callee can return false. stepForward(Acceptor child, StringRef errRef) eats a child element A child acceptor created by the `createChildAcceptor` method will be ultimately consumed by the parent through this method.

Field Detail

STRING_IGNORE	back to summary
public static final int STRING_IGNORE character literals are allowed, but Acceptor doesn't care its contents and where it is appeared. The caller doesn't need to call onText for literal. This mode is used for mixed contents.

STRING_PROHIBITED	back to summary
public static final int STRING_PROHIBITED only whitespaces are allowed. Acceptor will reject any string if it's not whitespaces. for example, <elementRule> of RELAX doesn't allow characters (except whitespaces) at all.

STRING_STRICT	back to summary
public static final int STRING_STRICT attentive handling of characters is required. Verifier has to keep track of exact contents of string and it must call onText for string accordingly.

Method Detail

createChildAcceptor back to summary

createChildAcceptor	back to summary
public Acceptor createChildAcceptor(StartTagInfo sti, StringRef refErr) creates an Acceptor that will accept the content model of the children of this moment. Once you create an acceptor, you need to call the `onAttribute` method for each present attribute, and then you need to call the `onEndAttributes` method. If an error occurs at this method, the bottom line is that the user cannot write this element here. Parameters sti:StartTagInfo this parameter provides the information about the start tag to the acceptor object. Usually attribute information is ignored, but sometimes they are used as hints. refErr:StringRef if this parameter is non-null, the implementation should try to detect the reason of error and recover from it. and this object should have the error message as its str field. Returns:Acceptor null If refErr is null, return null if the given start tag is not accepted. If refErr is non-null, return null only when the recovery is impossible.

public Acceptor createChildAcceptor(StartTagInfo sti, StringRef refErr)

creates an Acceptor that will accept the content model of the children of this moment.

Once you create an acceptor, you need to call the onAttribute method for each present attribute, and then you need to call the onEndAttributes method.

If an error occurs at this method, the bottom line is that the user cannot write this element here.

Parameters

sti:StartTagInfo: this parameter provides the information about the start tag to the acceptor object. Usually attribute information is ignored, but sometimes they are used as hints.
refErr:StringRef: if this parameter is non-null, the implementation should try to detect the reason of error and recover from it. and this object should have the error message as its str field.

Returns:Acceptor

null If refErr is null, return null if the given start tag is not accepted. If refErr is non-null, return null only when the recovery is impossible.

createClone	back to summary
public Acceptor createClone() clones this acceptor. You can keep a "bookmark" of the acceptor by cloning it. This is useful when you are trying to perform "partial validation". Cloned acceptor will behave in exactly the same way as the original one.

createClone

back to summary

public Acceptor createClone()

clones this acceptor.

You can keep a "bookmark" of the acceptor by cloning it. This is useful when you are trying to perform "partial validation".

Cloned acceptor will behave in exactly the same way as the original one.

getOwnerType	back to summary
public Object getOwnerType() gets the "type" object for which this acceptor is working. This method is used for type assignment. Actual Java type of return value depends on the implementation. Returns:Object null the callee should return null when it doesn't support type-assignment feature, or type-assignment is impossible for this acceptor (for example by ambiguous grammar).

getOwnerType

back to summary

public Object getOwnerType()

gets the "type" object for which this acceptor is working. This method is used for type assignment. Actual Java type of return value depends on the implementation.

Returns:Object: null the callee should return null when it doesn't support type-assignment feature, or type-assignment is impossible for this acceptor (for example by ambiguous grammar).

getStringCareLevel back to summary

getStringCareLevel	back to summary
public int getStringCareLevel() gets how this acceptor handles characters. This method makes it possible to optimize character handling. For many elements of data-oriented schemas, characters are completely prohibited. For example, In SVG, only handful elements are allowed to have #PCDATA and all other elements have element-only content model. Also, for many elements of document-oriented schemas, #PCDATA is allowed just about anywhere. In the former case, this method returns `STRING_PROHIBITED`. In other words, this declares that any onText(String) method with non-whitespace characters will always result in a failure. The caller can then exploit this property of the content model and can immediately signal an error when it finds characters, or discard any whitespace characters without keeping them in memory. In the latter case, this method returns `STRING_IGNORE`. This declares that any onText(String) call does not change anything at all. The caller can then exploit this property and discard any characeters it found. If non of the above applies, or the implementation is simply not capable of providing this information, then this method returns `STRING_STRICT`. In this case, the caller has to faithfully call the onText(String) method for all characeters it found. Although this method can be called anytime, it is intended to be called only once when the acceptor is first created. Returns:int one of the three constant values shown below.

public int getStringCareLevel()

gets how this acceptor handles characters.

This method makes it possible to optimize character handling. For many elements of data-oriented schemas, characters are completely prohibited. For example, In SVG, only handful elements are allowed to have #PCDATA and all other elements have element-only content model. Also, for many elements of document-oriented schemas, #PCDATA is allowed just about anywhere.

In the former case, this method returns STRING_PROHIBITED. In other words, this declares that any onText(String) method with non-whitespace characters will always result in a failure. The caller can then exploit this property of the content model and can immediately signal an error when it finds characters, or discard any whitespace characters without keeping them in memory.

In the latter case, this method returns STRING_IGNORE. This declares that any onText(String) call does not change anything at all. The caller can then exploit this property and discard any characeters it found.

If non of the above applies, or the implementation is simply not capable of providing this information, then this method returns STRING_STRICT. In this case, the caller has to faithfully call the onText(String) method for all characeters it found.

Although this method can be called anytime, it is intended to be called only once when the acceptor is first created.

Returns:int: one of the three constant values shown below.

isAcceptState	back to summary
public boolean isAcceptState(StringRef errRef) checks if this Acceptor is satisifed. Acceptor is said to be satisfied when given sequence of elements/strings is accepted by the content model. This method should be called before calling the stepForward method to make sure that the children is written properly. Parameters errRef:StringRef If this value is non-null, implementation can diagnose the error and sets the message to the object.

isAcceptState

back to summary

public boolean isAcceptState(StringRef errRef)

checks if this Acceptor is satisifed.

Acceptor is said to be satisfied when given sequence of elements/strings is accepted by the content model. This method should be called before calling the stepForward method to make sure that the children is written properly.

Parameters

errRef:StringRef: If this value is non-null, implementation can diagnose the error and sets the message to the object.

onAttribute	back to summary
public boolean onAttribute(String namespaceURI, String localName, String qName, String value, IDContextProvider context, StringRef refErr, DatatypeRef refType) Deprecated

onAttribute2	back to summary
public boolean onAttribute2(String namespaceURI, String localName, String qName, String value, IDContextProvider2 context, StringRef refErr, DatatypeRef refType) processes an attribute. For every attribute present in the document, you need to call this method. An error at this method typically indicates that this attribute is not allowed to appear here the attribute name was OK, but the value was incorrect. Parameters refErr:StringRef In case of an error, this object will receive the localized error message. Null is a valid value for this parameter. The implementation must provide some kind of message. refType:DatatypeRef If this parameter is non-null, this object will receive the datatype assigned to the attribute value. This feature is optional and therefore the implementation is not necessarily provide this information. Returns:boolean false if an error happens and refErr parameter was not provided. Otherwise true.

onAttribute2

back to summary

public boolean onAttribute2(String namespaceURI, String localName, String qName, String value, IDContextProvider2 context, StringRef refErr, DatatypeRef refType)

processes an attribute.

For every attribute present in the document, you need to call this method.

An error at this method typically indicates that

this attribute is not allowed to appear here
the attribute name was OK, but the value was incorrect.

Parameters

refErr:StringRef

In case of an error, this object will receive the localized error message. Null is a valid value for this parameter. The implementation must provide some kind of message.

refType:DatatypeRef

If this parameter is non-null, this object will receive the datatype assigned to the attribute value.

This feature is optional and therefore the implementation is not necessarily provide this information.

Returns:boolean

false if an error happens and refErr parameter was not provided. Otherwise true.

onEndAttributes back to summary

onEndAttributes	back to summary
public boolean onEndAttributes(StartTagInfo sti, StringRef refErr) notifies the end of attributes. This method needs to be called after the `onAttribute` method is called for each present attribute. An error at this method typically indicates that some required attributes are missing. Parameters sti:StartTagInfo This information is used to produce the error message if that is necessary. refErr:StringRef In case of an error, this object will receive the localized error message. Null is a valid value for this parameter. The implementation must provide some kind of message. Returns:boolean false if an error happens and refErr parameter was not provided. Otherwise true.

public boolean onEndAttributes(StartTagInfo sti, StringRef refErr)

notifies the end of attributes.

This method needs to be called after the onAttribute method is called for each present attribute.

An error at this method typically indicates that some required attributes are missing.

Parameters

sti:StartTagInfo: This information is used to produce the error message if that is necessary.
refErr:StringRef: In case of an error, this object will receive the localized error message. Null is a valid value for this parameter. The implementation must provide some kind of message.

Returns:boolean

false if an error happens and refErr parameter was not provided. Otherwise true.

onText	back to summary
public boolean onText(String literal, IDContextProvider context, StringRef refErr, DatatypeRef refType) Deprecated

onText2	back to summary
public boolean onText2(String literal, IDContextProvider2 context, StringRef refErr, DatatypeRef refType) processes a string literal. Parameters context:IDContextProvider2 an object that provides context information necessary to validate some datatypes. refErr:StringRef if this parameter is non-null, the implementation should try to detect the reason of error and recover from it. and this object should have the error message as its str field. refType:DatatypeRef if this parameter is non-null and the callee supports type-assignment, the callee will assign the DataType object to this variable. Caller must initialize refType.type to null before calling this method. If the callee doesn't support type-assignment or type-assignment is impossible for this literal (possibly by ambiguous grammar), this variable must kept null. Returns:boolean false if the literal at this position is not allowed.

onText2

back to summary

public boolean onText2(String literal, IDContextProvider2 context, StringRef refErr, DatatypeRef refType)

processes a string literal.

Parameters

context:IDContextProvider2: an object that provides context information necessary to validate some datatypes.
refErr:StringRef: if this parameter is non-null, the implementation should try to detect the reason of error and recover from it. and this object should have the error message as its str field.
refType:DatatypeRef: if this parameter is non-null and the callee supports type-assignment, the callee will assign the DataType object to this variable. Caller must initialize refType.type to null before calling this method. If the callee doesn't support type-assignment or type-assignment is impossible for this literal (possibly by ambiguous grammar), this variable must kept null.

Returns:boolean

false if the literal at this position is not allowed.

stepForward back to summary

stepForward	back to summary
public boolean stepForward(Acceptor child, StringRef errRef) eats a child element A child acceptor created by the `createChildAcceptor` method will be ultimately consumed by the parent through this method. It is the caller's responsibility to make sure that child acceptor is in the accept state. If it's not, that indicates that some required elements are missing (in other words, contents are not allowed to end here). It is the callee's responsibility to recover from error of unsatisified child acceptor. That is, even if the caller finds that there are missing elements, it is possible to call this method as if there was no such error. Returns:boolean false if an error happens. For example, if the implementation passes an acceptor which is NOT a child of this acceptor, then the callee can return false.

public boolean stepForward(Acceptor child, StringRef errRef)

eats a child element

A child acceptor created by the createChildAcceptor method will be ultimately consumed by the parent through this method.

It is the caller's responsibility to make sure that child acceptor is in the accept state. If it's not, that indicates that some required elements are missing (in other words, contents are not allowed to end here).

It is the callee's responsibility to recover from error of unsatisified child acceptor. That is, even if the caller finds that there are missing elements, it is possible to call this method as if there was no such error.

Returns:boolean: false if an error happens. For example, if the implementation passes an acceptor which is NOT a child of this acceptor, then the callee can return false.

public Interface Acceptor

Perform Validation

Downcasting

Field Summary

Method Summary

Field Detail

Method Detail