Falhas Base do Web Services Resource Framework
O WSRF (Web Services Resource Framework) fornece um tipo de elemento recomendado de mensagem de falha básica a partir do qual você pode derivar falhas específicas do serviço. A vantagem de um tipo básico comum é que todas as falhas podem, por padrão, conter informações comuns. Isso é útil em sistemas complexos nos quais as falhas podem ser registradas sistematicamente ou redirecionadas por várias camadas de software antes de serem analisadas.
- Um time stamp obrigatório.
- Um elemento que pode ser utilizado para indicar o originador da falha.
- Outros elementos que podem descrever e classificar a falha.
- ResourceUnkownFault
- Essa falha é utilizada para indicar que o WS-Resource não é conhecido pelo serviço que recebe a mensagem.
- ResourceUnavailableFault
- Essa falha é usada para indicar que o serviço da Web está ativo, mas temporariamente incapaz de fornecer acesso ao recurso.
<wsrf-bf:BaseFault>
<wsrf-bf:Timestamp>2005-05-31T12:00:00.000Z</wsrf-bf:Timestamp>
<wsrf-bf:Originator>
<wsa:Address>
http://www.example.org/Printer
</wsa:Address>
<wsa:ReferenceParameters>
<pr:pr-id>P1</pr:pr-id>
</wsa:ReferenceParameters>
</wsrf-bf:Originator>
<wsrf-bf:Description>Offline for service maintenance</wsrf-bf:Description>
<wsrf-bf:FaultCause>OFFLINE</wsrf-bf:FaultCause>
</wsrf-bf:BaseFault>
A classe BaseFault
Para aplicativos JAX-RPC, o WebSphere Application Server fornece mapeamentos de código Java™ para todos os tipos de elemento de falha de base definidos pelas especificações WSRF, formando uma hierarquia de exceção em que cada exceção Java estende a classe com.ibm.websphere.wsrf.BaseFault. Cada classe de falha segue um padrão semelhante.
package com.ibm.websphere.wsrf;
public class BaseFault extends Exception
{
public BaseFault()
{
...
}
public BaseFault(EndpointReference originator,
ErrorCode errorCode,
FaultDescription[] descriptions,
IOSerializableSOAPElement faultCause,
IOSerializableSOAPElement[] extensibilityElements,
Attribute[] attributes)
{
...
}
...
}
A Classe IOSerializableSOAPElement
Como a classe BaseFault estende a classe java.lang.Exception, ela deve implementar a interface java.io.Serializable. Para atender a esse requisito, todas as propriedades de uma instância BaseFault devem ser seriáveis. Como a classe javax.xml.soap.SOAPElement não é serializável, o WebSphere Application Server fornece uma classe IOSerializableSOAPElement, que você pode utilizar para agrupar uma instância javax.xml.soap.SOAPElement para fornecer uma forma serializável dessa instância.
// Obter uma instância da classe IOSerializableSOAPElementFactory
IOSerializableSOAPElementFactory factory = IOSerializableSOAPElementFactory.newInstance();
// Criar um IOSerializableSOAPElement a partir de um javax.xml.soap.SOAPElement
IOSerializableSOAPElement serializableSOAPElement = factory.createElement(soapElement);
// É possível recuperar o SOAPElement agrupado do IOSerializableSOAPElement
SOAPElement soapElement = serializableSOAPElement.getSOAPElement();
Quaisquer instâncias de BaseFault específicas do aplicativo também devem adotar esse requisito seriável.
Falhas Específicas do Aplicativo
<xsd:complexType name="PrinterFaultType">
<xsd:complexContent>
<xsd:extension base="wsrf-bf:BaseFaultType"/>
</xsd:complexContent>
</xsd:complexType>
import com.ibm.websphere.wsrf.BaseFault;
import com.ibm.websphere.wsrf.*;
import javax.xml.soap.SOAPFactory;
...
public void print(PrintRequest req) throws PrinterFault, ResourceUnknownFault
{
// Determinar a identidade da instância da impressora de destino.
PrinterState state = PrinterState.getState ();
if (state.OFFLINE)
{
try
{
// Obter uma instância do SOAPFactory
SOAPFactory soapFactory = SOAPFactory.newInstance();
// Criar o SOAPElement de causa da falha
SOAPElement faultCause = soapFactory.createElement("FaultCause");
faultCase.addTextNode("OFFLINE");
// Obter uma instância do IOSerializableSOAPElementFactory
IOSerializableSOAPElementFactory factory = IOSerializableSOAPElementFactory.newInstance();
// Criar um IOSerializableSOAPElement do SOAPElement faultCause
IOSerializableSOAPElement serializableFaultCause = factory.createElement(faultCause);
FaultDescription[] faultDescription = new FaultDescription[1];
faultDescription[0] = new FaultDescription("Off-line para manutenção de serviço");
throw new PrinterFault(
state.getPrinterEndpointReference(),
null,
faultDescription,
serializableFaultCause,
null,
null);
}
catch (SOAPException e)
{
...
}
}
...
import com.ibm.websphere.wsrf.BaseFault;
import com.ibm.websphere.wsrf.*;
...
try
{
printer1.print(job1);
}
catch (ResourceUnknownFault exc)
{
System.out.println("A operação emitiu o ResourceUnknownFault");
}
catch (PrinterFault exc)
{
System.out.println("A operação emitiu PrinterFault");
}
catch (BaseFault exc)
{
System.out.println("A exceção é outro BaseFault");
}
catch (Exception exc)
{
System.out.println("A exceção não é um BaseFault");
}
Binders Customizados
Ao definir uma nova falha de base no nível de aplicativo, por exemplo, a falha PrinterFault com o tipo PrinterFaultType mostrado anteriormente, é necessário fornecer um componente de ligação customizado para definir como o tempo de execução dos serviços da Web serializa a classe Java em uma mensagem XML apropriada e, inversamente, como serializar uma mensagem XML em uma instância da classe Java.
<customdatabinding:provider
xmlns:customdatabinding="http://www.ibm.com/webservices/customdatabinding/2004/06"
xmlns:pr="http://example.org/printer.xsd"
xmlns="http://www.ibm.com/webservices/customdatabinding/2004/06">
<mapeamento>
<xmlQName>pr:PrinterFaultType</xmlQName>
<javaName>PrinterFault</javaName>
<qnameScope>complexType</qnameScope>
<binder>PrinterFaultTypeBinder</binder>
</mapping>
</customdatabinding:provider>
A Classe BaseFaultBinderHelper
O WebSphere Application Server fornece uma classe BaseFaultBinderHelper, que fornece suporte para a serialização e desserialização dos dados que são específicos para uma classe BaseFault de raiz, que todas as classes BaseFault especializadas devem estender. Se um binder customizado utilizar a classe BaseFaultBinderHelper, ele precisará fornecer apenas a lógica adicional para serializar e desserializar os dados do BaseFault estendido.
import com.ibm.wsspi.wsrf.BaseFaultBinderHelper;
import com.ibm.wsspi.wsrf.BaseFaultBinderHelperFactory;
import com.ibm.wsspi.webservices.binding.CustomBinde;
import com.ibm.wsspi.webservices.binding.CustomBindingContext;
...
public PrinterFaultTypeBinder implements CustomBinder
{
// Obter uma instância do BaseFaultBinderHelper
private BaseFaultBinderHelper baseFaultBinderHelper = BaseFaultBinderHelperFactory.getBaseFaultBinderHelper();
public SOAPElement serialize(Object data, SOAPElement rootNode, CustomBindingContext context) throws SOAPException
{
// Serializar os dados específicos do BaseFault
baseFaultBinderHelper.serialize(rootNode, (BaseFault)data);
// Serializar quaisquer dados específicos de PrinterFault
...
// Retornar o PrinterFault serializado
return rootNode;
}
public Object deserialize(SOAPElement rootNode, CustomBindingContext context) throws SOAPException
{
// Criar uma instância de um PrinterFault
PrinterFault printerFault = new PrinterFault();
// Desserializar os dados específicos de BaseFault - quaisquer dados adicionais que
// formarem a extensão de PrinterFault serão retornados como um SOAPElement[].
SOAPElement[] printerFaultElements = baseFaultBinderHelper.deserialize(printerFault, rootNode);
// Desserializar os dados específicos de PrinterFault contidos no SOAPElement[] printerFaultElements
...
// Retornar o PrinterFault desserializado
return printerFault;
}
...
}