O usuário pode ter que fazer uma lista de itens aceitáveis e inaceitáveis de um conjunto de métodos em um serviço POJO. A listagem de itens aceitáveis e inaceitáveis é feita utilizando o atributo de filtro do elemento de métodos no elemento POJO. Os valores do filtro podem ser whitelisting e blacklisting. Se o filtro não for especificado, todos os métodos serão listados. O método getAddress da classe AddressLookup pode ser listado como aceitável especificando o serviço POJO como no exemplo a seguir.
O exemplo demonstra que apenas getAddress da classe AddressLookup é acessível utilizando o adaptador RPC. O mesmo método pode ser listado como inaceitável, como no exemplo a seguir.
O exemplo anterior demonstra que todos os métodos da classe AddressLookup, exceto getAddress, são acessíveis utilizando o adaptador RPC. Se o elemento de métodos do serviço POJO não for especificado ou o atributo de filtro não for especificado para os métodos, por padrão, todos os métodos serão listados como aceitáveis.
Em muitos casos, pode ser necessário acessar o objeto HttpServletRequest nos métodos que você está chamando a partir do JavaScriptTM. Isso pode ser realizado no Adaptador RPC tendo o HttpServletRequest como o primeiro parâmetro na chamada de método. A SMD (Simple Method Description) retornada não tem o objeto HttpServletRequest como um parâmetro e você pode chamar o método a partir do JavaScript sem transmitir esse parâmetro. Por exemplo, considere um método putNameInSession(HttpServletRequest req, String name). O XML correspondente a seguir é exibido.
Validadores são definidos utilizando os elementos de validadores no arquivo de configuração do adaptador do RPC. É possível especificar um conjunto de validadores para serviços individuais POJO. Antes da chamada de um método, o método de validação do validador especificado é chamado nos parâmetros do método. É possível especificar validadores separados para cada parâmetro de método. Todos os validadores estendem a classe abstrata com.ibm.websphere.rpcadapter.Validator. Uma outra maneira de validar é utilizando expressões regulares. O elemento validation-regex pode ser utilizado para especificar expressões comuns que correspondem aos valores de parâmetros. Se os valores de parâmetros não estiverem correspondendo à expressão comum, um erro de validação será criado.
Erros de validação resultam em um objeto de Erro sendo retornado no formato de JSON. Essas informações podem ser utilizadas para manipulação de erros. Os campos são descritos a seguir.
O Adaptador RPC agora suporta escopos para os objetos que ele expõe. Existem três escopos diferentes que são suportados pelo adaptador RPC, ou seja, Pedido, Sessão e Aplicativo, que podem ser especificados para armazenar o objeto exposto no pedido, sessão ou aplicativo. Quando o escopo é configurado como Aplicativo ou Sessão, uma vantagem adicional é que o objeto não é recriado toda vez, mas consultado a partir do escopo de Sessão ou Aplicativo. A chave utilizada é do formato "com.ibm.websphere.rpcadapter:ServiceName" em que ServiceName é o nome do objeto exposto. Para especificar essa chave, a tag de escopo é fornecida para cada objeto e pode conter os valores: Sessão, Pedido e Aplicativo. Consulte o exemplo a seguir.
Agora, o adaptador RPC suporta a inclusão de valores de retorno para a sessão. Para ativar essa inclusão de valores, a tag <add-to-session> precisa ser incluída conforme mostrado a seguir.
O Adaptador RPC agora suporta objetos complexos, por exemplo, objetos que podem conter outros objetos. Os objetos complexos são suportados como tipos de retorno bem como parâmetros de método. O Adaptador RPC agora pode serializar qualquer tipo de objeto complexo. Mapas e Coletas não são suportados como parâmetros para chamadas de método. Isto ocorre porque a classe dos objetos contidos no Mapa ou Coleta não pode ser identificada a partir de seu conteúdo sozinho. O suporte para isso requer sugestão de classe ou tipos parametrizados e ainda não é suportado. Também não é possível chamar métodos com parâmetros complexos por meio do HTTP-RPC, mesmo que tipos de retorno complexos sejam suportados.
Esse é um caso específico de suporte a objeto complexo. Por exemplo, A -> B -> A ou A contém B que contém A. O componente RPC Adapter do produto manipula este caso substituindo as ocorrências duplicadas de objetos por sinalizadores de substituição $jref (serialização JSON) ou $xref (serialização XML). Esses sinalizadores de substituição contêm informações que podem ser utilizadas para consultar o objeto original, isto é, uma expressão XPath no caso de XML e uma expressão JavaScript no caso de JSON. O suporte para manipulação de objetos recursivos pode ser ativado configurando o valor da tag <recursive-object-support> como true. Isso é mostrado no seguinte exemplo.
Geralmente, os objetos que precisam ser expostos podem ter determinados campos que o desenvolvedor de aplicativos não deseja expor por meio do serviço da Web JSON ou XML. O Adaptador RPC fornece a capacidade de suprimir campos a partir do objeto retornado. Essa supressão de campos pode ser ativada por meio da tag <serialized-params>. A configuração necessária para suprimir o campo postalCode da classe com.ibm.Address é mostrada abaixo. Essa configuração faz com que o campo postalCode da classe com.ibm.Address nunca seja serializado.
O usuário pode especificar aliases para classes. O alias é utilizado como nome do nó durante a serialização de XML. O seguinte exemplo mostra como o alias para endereço pode ser configurado.
O usuário pode especificar conversores para JSON/XML. Se um conversor for especificado para uma classe, ele será utilizado para a serialização JSON/XML
dessa classe. Todas as classes de conversor precisam implementar a interface com.ibm.websphere.rpcadapter.converters.IConverter
. Por padrão, o adaptador RPC é fornecido com os conversores a seguir.
Conversor | Uso |
com.ibm.websphere.rpcadapter.converters.sql.Date
|
Converter java.sql.Date em cadeia de data e hora. |
com.ibm.websphere.rpcadapter.converters.sql.Time
|
Converter java.sql.Time em cadeia de data e hora. |
com.ibm.websphere.rpcadapter.converters.sql.TimeStamp
|
Converter java.sql.TimeStamp em cadeia de data e hora. |
com.ibm.websphere.rpcadapter.converters.util.Date
|
Converter java.util.Date em cadeia de data e hora. |
É possível especificar conversores no arquivo RpcAdapterConfig.xml semelhante ao seguinte exemplo. A tag <subclass-support> pode ser usada para especificar que até mesmo as subclasses da classe de bean especificada devem ser convertidas pelo conversor de classe ao configurar o valor entre as tags para true. O padrão é configurar para false.
Por razões de segurança, o adaptador RPC pode ser configurado para emitir saída de comentário filtrado JSON quando utilizado para exportar métodos como serviços da Web JSON, como dados JSON agrupados com '/*' e '*/'. O Dojo tem a capacidade para processar esse comentário filtrado JSON no lado do cliente. Por padrão, esse recurso é desativado no RPCAdapter. Ele pode ser ativado configurando a tag filtrada como true no arquivo RPCAdapterConfig.xml, conforme mostrado no exemplo a seguir.
O suporte de segurança no adaptador RPC é desempenhado utilizando a segurança da Web Java EE. Todos os serviços que foram configurados para serem expostos ao cliente terão URLs exclusivas. O acesso a essas URLs é restringido utilizando a segurança da Web Java EE. Isto envolve criar uma região de segurança no Servidor de Aplicativos e, em seguida, definir o acesso baseado em função para URLs diferentes no arquivo de descritor de implementação, web.xml, e mapear essas funções para usuários ou grupos na região de segurança utilizando uma configuração específica do servidor. Esse recurso não pode ser usado isoladamente para chamadas em lote.
Além da Segurança da Web Java EE, o RPCAdapter também pode ser configurado para executar verificações de autorização para os serviços expostos e consequentemente permitir acesso apenas às funções específicas definidas no arquivo web.xml ou geronimo-web.xml. Para usar esse recurso, o padrão de url "/RPCAdapter/*" deve ser protegido através do arquivo web.xml. A próxima etapa envolve o uso da tag <role> para especificar se apenas um usuário com uma determinada função poderá acessar o serviço correspondente. Note que enquanto o RPCAdapter executa autorização de serviço, o aplicativo ainda é responsável por autenticar o usuário antes que o serviço protegido seja chamado. Se a autenticação não for feita antes que o serviço protegido seja chamado, o RPCAdapter não permitirá acesso o serviço correspondente. Isso é aplicável apenas para os métodos no serviço que já estiverem incluídos na lista de desbloqueio. O acesso a um serviço pode ser controlado conforme mostrado abaixo.
Os usuários podem agrupar em lote um conjunto de chamadas utilizando a API BatchService. Um novo depósito de informações do serviço de lote pode ser criado, inicializado e, então, enviado conforme a seguir.
Os métodos sobrecarregados podem ser expostos especificando um nome exclusivo para um método sobrecarregado fornecido e os tipos de parâmetros correspondentes no arquivo RpcAdapterConfig.xml.
É possível designar nomes as métodos que sejam diferentes dos reais utilizados na implementação do Java. Isto pode ser feito utilizando as tags <alias> e <name> de uma maneira semelhante que a utilizada para o sobrecarregamento de método. A única exceção é que os tipos de parâmetros não precisarão ser especificados se o método não estiver sobrecarregado.
Para acessar enterprise beans por meio do RPCAdapter, especifique as informações necessárias do módulo EJB no RPCAdapterConfig.xml. Os métodos no módulo EJB são expostos e você pode chamar um método diretamente do JavaScript.
Para acessar Beans de Sessão por meio do RPCAdapter, especifique as interfaces remota e local, o jndi-name para a consulta do módulo EJB e os métodos implementados. No caso do EJB 3.0, as interfaces remota e local são
substituídas por uma única interface geralmente chamada de interface de negócios. Portanto, especifique a interface de negócios utilizando a tag <business-interface>. A tag <ejb-name> é utilizada para associar um nome lógico ao módulo
EJB. O <jndi-name> é utilizado para consultar módulos EJB. O jndi-name especificado pelo usuário no arquivo RPCAdapterConfig.xml deve corresponder ao jndi-name especificado no arquivo web.xml. No caso do EJB 3.0, prefixe
o nome jndi com "java:comp/env/" se o Servidor de Aplicativos usado for o WebSphere® Application Server Community Edition. No caso do WebSphere Application Server, se o EJB3.0 estiver sendo utilizado, o jndi-name
na tag <jndi-name> deverá ser prefixado com a palavra-chave "ejblocal:". Você deve fornecer o tipo de bean de sessão, sem preservação de estado ou com preservação de estado, utilizando a tag <session-type>.
Uma entrada de exemplo do Bean de Sessão sem Preservação de Estado no arquivo RPCAdapterConfig.xml é mostrada no exemplo a seguir.
Em Beans de Sessão com Preservação de Estado, a interface inicial pode conter mais de uma função de criação. Nesse caso, especifique a função de criação que deve ser chamada. Utilize a tag <create> para declarar a função de criação no arquivo RPCAdapterConfig.xml. O trecho de código do Bean de Sessão com Preservação de Estado para o EJB 2.1 é mostrado a seguir.
O suporte a anotações permite expor os serviços diretamente a partir do código, em vez de configurá-los no arquivo RPCAdapterConfig.xml. Para ativar esse recurso, o arquivo RPCAdapter-annotation.jar é fornecido neste release. Coloque esse arquivo jar no diretório WEB-INF/lib do aplicativo da Web utilizando esse recurso. Você deve anotar a classe que contém os métodos a serem expostos com o @Pojo e os métodos correspondentes às anotações @Method e @Params. Uma classe anotada torna-se visível para o RPCAdapter por meio do arquivo web.xml. Especifique o nome canônico da classe anotada como um valor "init-param" para o RPCAdapter. Mencione o nome "init-param" correspondente como classn, em que n é qualquer número. A seguir, um trecho de código de amostra.
No Adaptador RPC, o formato de saída é JSON ou XML.
As diversas saídas XML geradas sob diferentes cenários são listadas a seguir.
Se o tipo de retorno for nulo, a saída XML gerada será uma tag de resultado vazio, conforme mostrado a seguir.
Se o método no JavaBeans for public int getSalary()
, a saída será semelhante ao seguinte exemplo:
public String getMessage()
, a saída será semelhante ao seguinte exemplo:
public Boolean isLeapYear(int year)
, a saída será semelhante ao seguinte exemplo:
Para o tipo de retorno Coleta, a saída é um conjunto de elementos, com cada elemento representando uma entrada na coleta. Se a coleta tiver instâncias de um tipo de objeto suprimido, essa entrada será ignorada.
public Collection getEmployees()
e a coleta retornada contiver instâncias de Employee, uma saída de amostra será semelhante ao seguinte exemplo.
Para o tipo de retorno Matriz, a saída é um conjunto de Elementos, com cada elemento representando uma entrada na matriz.
public Employee[] getEmployees()
e a Matriz retornada consistir de instâncias de Employee, uma saída de amostra será semelhante ao seguinte exemplo.
Para o tipo de retorno Mapa, a saída será um conjunto de Elementos, com cada elemento representando um par de chave-valor no mapa. O nome do nó é a chave.
Se o método no JavaBeans for public Map getDepartments()
e o mapa retornado for um par de valor de chave de código de departamento para detalhes de departamento, uma saída de amostra será semelhante ao seguinte exemplo.
Para o tipo de retorno JavaBeans, todos os métodos de leitura e campos públicos sem um método de leitura serão considerados para a serialização XML. Os JavaBeans são representados por um elemento. O nome do nó desse elemento será o tipo de JavaBeans que ele representa. Se qualquer alias for especificado para o bean, ele será utilizado como nome do nó.
Se o método no JavaBeans for public Employee getEmployee()
, uma saída de amostra será semelhante ao seguinte exemplo:
As diversas saídas de JSON geradas em vários cenários são explicadas a seguir.
Se o tipo de retorno for nulo, a saída de JSON gerada será um objeto de resultado JSON.
public int getSalary()
, a saída será semelhante ao seguinte exemplo:
public String getMessage()
, a saída será semelhante ao seguinte exemplo:
public Boolean isLeapYear(int year)
, a saída será semelhante ao seguinte exemplo:
Para o tipo de retorno Coleta, a saída é um conjunto de elementos, com cada elemento representando uma entrada na coleta. Se a coleta tiver instâncias de um tipo de objeto suprimido, essa entrada será ignorada.
public Collection getEmployees()
e a coleta retornada contiver instâncias de Employee, uma saída de amostra será semelhante ao seguinte exemplo.
Para o tipo de retorno Matriz, a saída é um conjunto de Elementos, com cada elemento representando uma entrada na matriz.
public Employee[] getEmployees()
e a Matriz retornada consistir de instâncias de Employee, uma saída de amostra será semelhante ao seguinte exemplo.
Para o tipo de retorno Mapa, a saída será um conjunto de pares de chave-valor.
Se o método no JavaBeans for public Map getDepartments()
e o mapa retornado for um par de valor de chave de código de departamento para detalhes de departamento, uma saída de amostra será semelhante ao seguinte exemplo.
Os JavaBeans são representados como pares de valor da chave com a chave com o nome do campo e o valor como o valor do campo. Apenas campos públicos e campos com getters são serializados.
Se o método no JavaBeans for public Employee getEmployee()
, uma saída de amostra será semelhante ao seguinte exemplo:
O adaptador RPC pode ser configurado para (1) instanciar o pedido por JavaBeans ou (2) para reutilizar as instâncias por usuário. (Por exemplo, um objeto carrinho de compras poderá ser configurado como este último.) O comportamento padrão é instanciar novos JavaBeans por pedido. A reutilização é configurada por meio das informações do descritor do Bean. Consulte a documentação da API SampleBeanInfo para obter detalhes.
Alguns comandos são desenvolvidos sem a expectativa de serem expostos diretamente como serviços. Nesses casos, um acessador JavaBeans pode ser desenvolvido para conter a lógica aplicada. Por exemplo, o EJB ShoppingCart na amostra do PlantsByWebSphere inclui um método addItem(StoreItem item). O objeto StoreItem inclui o preço do item, portanto esse design presume que apenas as origens confiáveis chamarão o método, como o exemplo a seguir no servlet ShoppingServlet.