Skip to content

Commit b332c69

Browse files
poutsmapoutsma
committed
SWS-354
1 parent ec3c0e9 commit b332c69

File tree

1 file changed

+119
-0
lines changed

1 file changed

+119
-0
lines changed

‎src/docbkx/server.xml‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -718,6 +718,125 @@ public class MarshallingOrderEndpoint extends AbstractMarshallingPayloadEndpoint
718718
<literal>marshaller</literal> bean.
719719
</para>
720720
</section>
721+
<section>
722+
<title>Using Spring <interfacename>Validator</interfacename> with Marshalling Endpoints</title>
723+
<para>
724+
It is possible to use <ulink url="http://static.springframework.org/spring/docs/2.5.x/reference/validation.html#validator"><interfacename>Validator</interfacename></ulink>
725+
objects in conjunction with marshalling endpoints in order to validate the unmarshalled payloads.
726+
Spring-WS provides 2 extensions of <classname>AbstractMarshallingPayloadEndpoint</classname> for that purpose:
727+
<classname>AbstractValidatingMarshallingPayloadEndpoint</classname> and
728+
<classname>AbstractFaultCreatingValidatingMarshallingPayloadEndpoint</classname>. The former is the most
729+
general whereas the latter specializes in creating SOAP faults in response to validation errors.
730+
</para>
731+
<para>
732+
Both classes support setting one or more <interfacename>Validator</interfacename> objects via the
733+
<property>validator</property> and <property>validators</property> properties respectively.
734+
Note that all of the injected validators
735+
<emphasis role="bold">must</emphasis> support the request object (through the <methodname>supports</methodname> method)
736+
or else an <exceptionname>IllegalArgumentException</exceptionname> will be thrown.
737+
</para>
738+
<note>
739+
<para>
740+
The default request object name used in the validator is <literal>request</literal>.
741+
The error codes are generated in consequence. For instance, assuming a POJO with a
742+
"<property>name</property>" property of type <literal>java.lang.String</literal>,
743+
calling <methodname>errors.rejectValue("name","invalidValue")</methodname> in the
744+
<methodname>validate</methodname> method of a <interfacename>Validator</interfacename>
745+
generates the following error codes:
746+
<literal>invalidValue.request.name</literal>, <literal>invalidValue.name</literal>,
747+
<literal>invalidValue.java.lang.String</literal> and <literal>invalidValue</literal>.
748+
Similarly, calling <methodname>errors.reject("invalidValue")</methodname>
749+
generates <literal>invalidValue.request</literal> and <literal>invalidValue</literal> as error codes.
750+
</para>
751+
</note>
752+
<section>
753+
<title><classname>AbstractValidatingMarshallingPayloadEndpoint</classname></title>
754+
<para>
755+
Subclasses of <classname>AbstractValidatingMarshallingPayloadEndpoint</classname>
756+
implement the validation error handling logic by overriding the <methodname>onValidationErrors</methodname>
757+
method. This method is called when a validation error occurs and its return value
758+
indicates whether the endpoint should continue processing the request or not.
759+
</para>
760+
<para>
761+
In the following example, a custom error POJO is marshalled and sent as a response:
762+
</para>
763+
<programlisting><![CDATA[public class MyMarshallingEndpoint extends AbstractValidatingMarshallingPayloadEndpoint{
764+
765+
private MessageSource messageSource;
766+
767+
protected Object invokeInternal(Object requestObject) throws Exception {
768+
// process the payload
769+
}
770+
771+
protected boolean onValidationErrors(MessageContext messageContext, Object requestObject, Errors errors) {
772+
FieldError error = errors.getFieldError("name");
773+
CustomError customError = new CustomError();
774+
String message = messageSource.getMessage(error, Locale.ENGLISH);
775+
customError.setMessage(message);
776+
try {
777+
getMarshaller().marshal(customError, messageContext.getResponse().getPayloadResult());
778+
} catch (XmlMappingException ex) {
779+
// handle the exception
780+
} catch (IOException ex) {
781+
// handle the exception
782+
}
783+
return false;
784+
}
785+
}
786+
]]></programlisting>
787+
</section>
788+
<section>
789+
<title><classname>AbstractFaultCreatingValidatingMarshallingPayloadEndpoint</classname></title>
790+
<para>
791+
Endpoints of this type generate a SOAP fault whenever a validation error occurs.
792+
By default, a fault detail element is generated for each validation error.
793+
The error codes are resolved using the application context message source.
794+
</para>
795+
<para>
796+
The properties of <classname>AbstractFaultCreatingValidatingMarshallingPayloadEndpoint</classname>
797+
have sensible defaults, which makes its subclasses quite simple to configure as in the following example:
798+
</para>
799+
<programlisting><![CDATA[<bean id="messageSource" class="org.springframework.context.support.ResourceBundleMessageSource">
800+
<property name="basename" value="message"/>
801+
</bean>
802+
803+
<bean id="orderValidator" class="samples.OrderValidator"/>
804+
805+
<bean id="marshallingOrderEndpoint" class="samples.MarshallingOrderEndpoint">
806+
<property name="marshaller" ref="marshaller"/>
807+
<property name="unmarshaller" ref="marshaller"/>
808+
<property name="validator" ref="orderValidator"/>
809+
</bean>
810+
]]></programlisting>
811+
<para>
812+
In case of validation error, here is how the response might look like:
813+
</para>
814+
<programlisting><![CDATA[<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
815+
<SOAP-ENV:Header/>
816+
<SOAP-ENV:Body>
817+
<SOAP-ENV:Fault>
818+
<faultcode>SOAP-ENV:Client</faultcode>
819+
<faultstring xml:lang="en">Validation error</faultstring>
820+
<detail>
821+
<spring-ws:ValidationError xmlns:spring-ws="http://springframework.org/spring-ws">
822+
invalid user id: Ernie
823+
</spring-ws:ValidationError>
824+
<spring-ws:ValidationError xmlns:spring-ws="http://springframework.org/spring-ws">
825+
invalid order
826+
</spring-ws:ValidationError>
827+
</detail>
828+
</SOAP-ENV:Fault>
829+
</SOAP-ENV:Body>
830+
</SOAP-ENV:Envelope>
831+
]]></programlisting>
832+
<para>
833+
It is possible though to customize various aspects of the generated SOAP faults, such as the fault string
834+
and the soap detail.
835+
Please refer to the <ulink url="http://static.springframework.org/spring-ws/site/apidocs/org/springframework/ws/soap/server/endpoint/AbstractFaultCreatingValidatingMarshallingPayloadEndpoint.html">Javadoc</ulink>
836+
for the full list of available options.
837+
</para>
838+
</section>
839+
</section>
721840
<section id="server-at-endpoint">
722841
<title><interfacename>@Endpoint</interfacename></title>
723842
<para>

0 commit comments

Comments
 (0)