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.

As informações comuns incluem os seguintes itens:
  • 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.
As duas falhas padrão são definidas para serem utilizadas com cada operação WSRF:
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.
O seguinte fragmento XML mostra um exemplo de elemento de falha base:
 <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>
Importante: Os elementos e classes abordados no restante deste tópico se aplicam apenas a aplicativos JAX-RPC. Se o seu aplicativo usa JAX-WS, utilize os artefatos gerados, por exemplo, pela ferramenta wsimport, do documento WSLD do aplicativo e do esquema XML que definem o uso do tipo BaseFault específico.

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.

Por exemplo, a classe BaseFault define os dois construtores a seguir:
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.

Crie uma instância de IOSerializableSOAPElement utilizando a classe IOSerializableSOAPElementFactory, conforme a seguir:
// 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

Os aplicativos podem definir suas próprias extensões para o elemento BaseFault. Utilize extensões do tipo XML para definir um novo tipo de XML para a falha de aplicativo que estende o elemento BaseFaultType. Por exemplo, o seguinte fragmento XML cria um novo elemento PrinterFaultType:
 <xsd:complexType name="PrinterFaultType">
   <xsd:complexContent>
     <xsd:extension base="wsrf-bf:BaseFaultType"/>
   </xsd:complexContent>
 </xsd:complexType>
O exemplo a seguir mostra como um aplicativo de serviço da Web, cuja definição WSDL pode definir uma operação de impressão que declara duas mensagens wsdl:fault, constrói um objeto PrinterFault:
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)
            {
               ...
            }
        }
        ...
O código a seguir mostra como as hierarquias de falha de base são manipuladas como hierarquias de exceçãoJava:
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.

O binder customizado deve implementar a interface com.ibm.wsspi.webservices.binding.CustomBinder. Empacote o binder em um arquivo JAR (Java archive) juntamente com um arquivo de metadados declarativo, CustomBindingProvider.xml, no diretório /META-INF/services do arquivo JAR. Esse arquivo de metadados define o relacionamento entre o binder customizado, a implementação BaseFault e o tipo BaseFault Java. Por exemplo, é possível definir um binder customizado chamado PrinterFaultTypeBinder, para mapear entre o elemento PrinterFaultType XML e sua implementação Java , PrinterFault, como segue:
<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.

O código a seguir mostra como você pode implementar um binder customizado para que o elemento PrinterFaultType aproveite o suporte da classe BaseFaultBinderHelper:
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;
   }
 
  ...
 
}

Ícone que indica o tipo de tópico Tópico de Conceito



Ícone de registro de data e hora Última atualização: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=cwbs_wsrf_basefault
Nome do arquivo: cwbs_wsrf_basefault.html