Entity Manager em um Ambiente Distribuído

É possível usar a API EntityManager com um ObjectGrid local ou em um ambiente distribuído do eXtreme Scale . A principal diferença é como você se conecta a esse ambiente remoto. Após você estabelecer uma conexão, não existe diferença entre o uso de um objeto Session ou uma API do EntityManager.

Arquivos de Configuração Necessários

Os seguintes arquivos de configuração XML são necessários:
  • Arquivo XML descritor do ObjectGrid
  • Arquivo XML descritor da entidade
  • Arquivo XML descritor de implementação ou de grade de dados

Esses arquivos especificam as entidades e os BackingMaps que um servidor hospeda.

O arquivo descritor de metadados da entidade contém uma descrição das entidades que são utilizadas. No mínimo, você deve especificar o nome e a classe da entidade. Se você estiver executando em um ambiente Java Platform, Standard Edition 5, oeXtreme Scale automaticamente lê a classe da entidade e suas anotações. É possível definir atributos XML adicionais se a classe de entidade não tiver anotações ou se você precisar substituir os atributos de classe. Se estiver registrando as entidades sem classe, forneça todas as informações da entidade apenas no arquivo XML.

É possível usar o seguinte fragmento de configuração XML para definir uma grade de dados com entidades. Nesse fragmento, o servidor cria um ObjectGrid com o nome bookstore e um mapa de apoio associado com o nome order. O fragmento no arquivo objectgrid.xml refere-se ao arquivo entity.xml. Nesse caso, o arquivo entity.xml contém uma entidade, a Order.

objectgrid.xml
<objectGridConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://ibm.com/ws/objectgrid/config ../objectGrid.xsd"
 xmlns="http://ibm.com/ws/objectgrid/config">

 <objectGrids>
    <objectGrid name="bookstore" entityMetadataXMLFile="entity.xml">
     <backingMap name="Order"/>
    </objectGrid>
</objectGrids>

</objectGridConfig>

Este arquivo objectgrid.xml especifica o arquivo entity.xml com o atributo entityMetadataXMLFile. O valor pode ser um diretório relativo ou um caminho absoluto.
  • Para um relatório relativo: Especifique o local relativo com o local do arquivo objectgrid.xml.
  • Para um caminho absoluto: Especifique o local com um formato de URL, como file:// ou http://.
Este é um exemplo do arquivo entity.xml:
entity.xml
<entity-mappings xmlns="http://ibm.com/ws/projector/config/emd"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://ibm.com/ws/projector/config/emd ./emd.xsd">
	<entity class-name="com.ibm.websphere.tutorials.objectgrid.em.
distributed.step1.Order" name="Order"/> </entity-mappings>
Este exemplo assume que a classe Order teria os campos orderNumber e desc anotados de modo semelhante.

A seguir há um exemplo do arquivo server.properties sem classe equivalente:

classless entity.xml
<entity-mappings xmlns="http://ibm.com/ws/projector/config/emd"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://ibm.com/ws/projector/config/emd ./emd.xsd">
	<entity class-name="@Order " name="Order">
	    <description>"Entity named: Order"</description>
        <attributes>
            <id name="orderNumber" type="int"/>
            <basic name="desc" type="java.lang.String"/>
        </attributes>
	</entity>
</entity-mappings>
Para obter informações sobre como iniciar os servidores, consulte Iniciando Servidores Independentes. É possível usar ambos os arquivos deployment.xml e objectgrid.xml para iniciar o servidor de catálogos.

Conectando-se a um Servidor eXtreme Scale Distribuído

O seguinte código ativa o mecanismo de conexão para um cliente e servidor no mesmo computador:
String catalogEndpoints="localhost:2809";
URL clientOverrideURL= new URL("file:etc/emtutorial/distributed/step1/objectgrid.xml");
ClientClusterContext clusterCtx = ogMgr.connect(catalogEndpoints, null, clientOverrideURL);
ObjectGrid objectGrid=ogMgr.getObjectGrid(clusterCtx, "bookstore");
No fragmento de código anterior, observe a referência ao servidor eXtreme Scale remoto. Após estabelecer uma conexão, é possível invocar os métodos de API do EntityManager como persist, update, remove e find.
Atenção: Quando estiver usando entidades, passe o arquivo XML do descritor do ObjectGrid de substituição para o método connect. Se um valor nulo é passado para a propriedade clientOverrideURL e o cliente tem uma estrutura de diretório doferente da estrutura de diretório do servidor, então o cliente pode falhar em localizar os arquivos XML do descritor de entidade ou ObjectGrid. No mínimo, os arquivos XML de entidade e ObjectGrid para o servidor podem ser copiados para o cliente.
Anteriormente, o uso de entidades no cliente ObjectGrid exigia que você deixasse o XML do ObjectGrid e o XML da entidade disponíveis para o cliente de uma das duas maneiras a seguir:
  1. Passe um XML do ObjectGrid de substituição para o método ObjectGridManager.connect(String catalogServerEndpoints, ClientSecurityConfiguration securityProps, URL overRideObjectGridXml).

    String catalogEndpoints="myHost:2809";
    URL clientOverrideURL= new URL("file:etc/emtutorial/distributed/step1/objectgrid.xml");
    ClientClusterContext clusterCtx = ogMgr.connect(catalogEndpoints, null, clientOverrideURL);
    ObjectGrid objectGrid=ogMgr.getObjectGrid(clusterCtx, "bookstore");

  2. Transmita nulo para o arquivo de substituição e certifique-se de que o XML do ObjectGrid e o XML da entidade referida estejam disponíveis para o cliente no mesmo caminho que no servidor.

    String catalogEndpoints="myHost:2809";
    ClientClusterContext clusterCtx = ogMgr.connect(catalogEndpoints,
    null, null);
    ObjectGrid objectGrid=ogMgr.getObjectGrid(clusterCtx, "bookstore");

Os arquivos XML eram necessários, independentemente de você querer ou não utilizar um subconjunto de entidades no lado do cliente. Esses arquivos não são mais necessários para o uso de entidades, conforme definido pelo servidor. Em vez disso, transmita nulo como o parâmetro overRideObjectGridXml como na opção 2 da seção anterior. Se o arquivo XML não estiver localizado no mesmo caminho configurado no servidor, o cliente usa a configuração da entidade no servidor.

Entretanto, se você utilizar entidades do subconjunto no cliente, será necessário fornecer um XML do ObjectGrid de substituição na opção 1.

Esquema do Lado do Cliente e do Servidor

O esquema do lado do servidor define o tipo de dado armazenado nos mapas em um servidor. O esquema do lado do cliente é um mapeamento para objetos de aplicativo do esquema no servidor. Por exemplo, é possível ter o seguinte esquema do lado do servidor:
@Entity
class ServerPerson
{
  @Id String ssn;
  String firstName;
  String surname;
  int age;
  int salary;
}
Um cliente pode ter um objeto anotado como no exemplo a seguir:
@Entity(name="ServerPerson")
class ClientPerson
{
  @Id @Basic(alias="ssn") String socialSecurityNumber;
  String surname;
}
Este cliente, então, toma uma entidade do lado do servidor e projeta o subconjunto da entidade no objeto do cliente. Esta projeção leva à economia de largura de banda e de memória em um cliente porque o cliente tem somente as informações que ele precisa em vez de todas as informações que estiverem na entidade do lado do servidor. Aplicativos diferentes podem utilizar seus próprios objetos em vez de forçarem todos os aplicativos a compartilharem um conjunto de classes para o acesso a dados.

O arquivo XML descritor da entidade do lado do cliente é necessário nos seguintes casos: se o servidor estiver em execução com entidades baseadas em classe enquanto o lado do cliente está em execução sem classes; ou se o servidor estiver sem classes e o cliente utilizar entidades baseadas em classe. Um modo de cliente sem classe permite que o cliente ainda execute consultas de entidade sem precisar acessar classes físicas. Supondo que o servidor tenha registrado a entidade ServerPerson acima, o cliente poderia substituir a grade de dados por um arquivo entity.xml como a seguir:

<entity-mappings xmlns="http://ibm.com/ws/projector/config/emd"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://ibm.com/ws/projector/config/emd ./emd.xsd">
	<entity class-name="@ServerPerson " name="Order">
	    <description>"Entity named: Order"</description>
        <attributes>
            <id name="socialSecurityNumber" type="java.lang.String"/>
            <basic name="surname" type="java.lang.String"/>
        </attributes>
	</entity>
</entity-mappings>

Este arquivo atinge uma entidade de subconjunto equivalente no cliente, sem exigir que o cliente forneça a classe anotada real. Se o servidor não tiver classe e o cliente tiver, o cliente fornecerá um arquivo XML do descritor de entidade de substituição. Este arquivo XML do descritor de entidade contém uma substituição para a referência do arquivo de classe.

Fazendo Referência ao Esquema

Se seu aplicativo estiver em execução no Java SE 5, o aplicativo poderá ser incluído nos objetos usando anotações. O EntityManager pode ler o esquema nas anotações de tais objetos. O aplicativo fornece ao tempo de execução do eXtreme Scale referências a esses objetos utilizando o arquivo entity.xml, que é referido no arquivo objectgrid.xml. O arquivo entity.xml lista todas as entidades, cada uma associada a uma classe ou a um esquema. Se um nome de classe apropriado for especificado, o aplicativo tentará ler as anotações do Java SE 5 a partir dessas classes para determinar o esquema. Se você não anotar o arquivo de classe ou especificar um identificador sem classe como o nome de classe, o esquema será tirado do arquivo XML. O arquivo XML é utilizado para especificar todos os atributos, chaves e relacionamentos para cada entidade.

Uma grade de dados local não precisa de arquivos XML. O programa pode obter uma referência do ObjectGrid e invocar o método ObjectGrid.registerEntities para especificar uma lista de classes anotadas do Java SE 5 ou um arquivo XML.

O tempo de execução utiliza o arquivo XML ou uma lista de classes anotadas para localizar nomes de entidades, nomes e tipos de atributos, tipos e campos chave e relacionamentos entre entidades. Se o eXtreme Scale estiver executando em um servidor ou em modo independente, então ele cria automaticamente um mapa nomeado após cada entidade. Estes mapas podem ser customizados adicionalmente utilizando o arquivo objectgrid.xml ou APIs configuradas pelo aplicativo ou por estruturas de injeção tais como Spring.

Arquivo Descritor de Metadados da Entidade

Consulte Arquivo emd.xsd para obter informações adicionais sobre o arquivo descritor de metadados.