Pré-requisitos de Programação

São descritos aqui os métodos comuns, as etapas de pré-requisito e outras informações necessárias aos programadores que estão desenvolvendo aplicativos do gerenciador de membro virtual.

Importando Pacotes do Gerenciador de Membro Virtual

Antes de integrar funções de gerenciador de membro virtual em seu aplicativo, você deve importar pacotes de gerenciador de membro virtual e outros pacotes relacionados. O exemplo a seguir mostra os pacotes que você deve importar e como definir a classe.

import java.util.Hashtable;
import java.util.List;

import com.ibm.websphere.wim.SchemaConstants;
import com.ibm.websphere.wim.Service;
import com.ibm.websphere.wim.client.LocalServiceProvider;
import com.ibm.websphere.wim.ras.WIMTraceHelper;

import java.security.PrivilegedActionException;
import java.security.PrivilegedExceptionAction;
import javax.security.auth.Subject;
import javax.security.auth.login.LoginContext;
import com.ibm.websphere.security.auth.WSSubject;
import com.ibm.websphere.security.auth.callback.WSCallbackHandlerImpl;
import commonj.sdo.DataObject;

Obtendo o Serviço do Gerenciador de Membro Virtual e Outros Métodos Comuns

O serviço do gerenciador de membro virtual poderá ser obtido do EJB remoto ou da JVM local, se o seu aplicativo estiver sendo executado no WebSphere Application Server.

Nota: Se você estiver chamando o virtual member manager usando APIs EJB remotas, assegure-se de que wim.ear esteja implementado. Para obter mais informações, consulte Instalando o gerenciador de membro virtual

O seguinte aplicativo base de amostra contém métodos locateService() que mostram como obter o serviço do gerenciador de membro virtual, bem como outros métodos comuns usados nas amostras de código em diversas operações do gerenciador de membro virtual. Substitua as variáveis mostradas em itálico no seguinte código pelos valores reais que você precisa.

/**
 * This is a base application which defines common methods that are 
 * used by other code samples.
 **/
public class BaseApp implements SchemaConstants
{
    /**
     * Common variable declaration: update based on the environment
     **/
    static final String HOST = "localhost";       // host name of the WebSphere Application Server
    static final String BOOTSTRAP_PORT = "2809";  // Bootstrap/RMI port number
    
    // Virtual member manager service that is used to make API calls
    static Service service = null;

    /**
     * Locates virtual member manager service using a remote EJB
     * @param ejbJndiName JNDI name of the EJB. 
     * Default EJB name is "ejb/com/ibm/websphere/wim/ejb/WIMServiceHome"
     **/
    public static Service locateService(String ejbJndiName)
    {
        try {
            // Remote access virtual member manager Service EJB
            Hashtable environment = new Hashtable();
            
            String providerURL = "corbaloc:iiop:" + HOST + ":" + BOOTSTRAP_PORT;
            environment.put(LocalServiceProvider.PROVIDER_URL, providerURL);
            if (ejbJndiName == null) {
                ejbJndiName = "ejb/com/ibm/websphere/wim/ejb/WIMServiceHome";
            }
            environment.put(LocalServiceProvider.EJB_JNDI_NAME, ejbJndiName);
            
            service = new LocalServiceProvider(environment);
        }
        catch (Exception e) {
            e.printStackTrace();
        }
        return service;
    }
    
    /**
     * Locates virtual member manager service in local JVM
     **/
    public static Service locateService()
    {
        try { 
            // Local access virtual member manager Service 
            return new LocalServiceProvider(null);
        }
        catch (Exception e)
        {
            e.printStackTrace();
        }

        return null;
    }

    /**
     * Runs action as specified user
     * @param user user name
     * @param password password of the user
     * @param action Action to invoke after successful login of the user
     * @return Object returned by the action
     **/
    public static Object runAsUser(String user, String password, PrivilegedExceptionAction action) throws Exception
    {
        LoginContext loginContext;
        Subject subject;

        // Login using the userid and password that was passed, which has the required role
        loginContext = new LoginContext("WSLogin", new WSCallbackHandlerImpl(user, "", password));
        loginContext.login();
        subject = loginContext.getSubject();

        try {
            return WSSubject.doAs(subject, action);
        }
        catch (PrivilegedActionException excp) {
            throw (Exception) excp.getCause();
        }
    }

    public static String printDO(DataObject obj)
    {
        return WIMTraceHelper.printDataObject(obj);
    }

    /**
     * Loop through the entities in the DataObject and print its uniqueName
     * @param root input DataObject
     */
    @SuppressWarnings("unchecked")
    public static void printIdentifiers(DataObject root) throws Exception
    {
        // Get all entities in the DataObject
        List entities = root.getList(SchemaConstants.DO_ENTITIES);
        for (int i = 0; i < entities.size(); i++) {
            DataObject ent = (DataObject) entities.get(i);
            // Get the entity Identifier
            DataObject id = ent.getDataObject(SchemaConstants.DO_IDENTIFIER);
            if (id != null) {
                String uniqueName = id.getString(SchemaConstants.PROP_UNIQUE_NAME);
                System.out.println("UniqueName is  -> " +uniqueName);
            }
            else {
                System.out.println("Missing Identifier");
            }
        }
    }
}
Nota: Configure a propriedade de sistema a seguir na JVM cliente, se seu aplicativo chamar APIs do gerenciador de membro virtual no modo local:
org.eclipse.emf.ecore.EPackage.Registry.INSTANCE=com.ibm.ws.wim.util.VMMEMFGlobalDelegatorRegistry
Se você não configurar essa propriedade de sistema, a implementação EMF padrão entrará em vigor, a qual não suporta ambiente com vários domínios de segurança, e pode corromper o esquema EMF e provocar erro de violação de esquema.
Limitação: O dano ao esquema EMF também pode ocorrer quando um cliente EJB remoto acessa o EMF em um ambiente de segurança com vários domínios, se o cliente EJB estiver em um processo do servidor que não é o WebSphere Application Server ou é anterior ao WebSphere Application Server versão 8.0. Essa é uma limitação no ambiente com vários domínios de segurança, já que um processo do cliente EJB remoto pode usar no máximo um serviço de domínio por vez. Se um cliente EJB remoto tentar operar em diversos serviços de domínio simultaneamente, o registro do esquema EMF do processo do cliente será danificado e ocorrerá erro inesperado de violação de esquema no aplicativo cliente.

Chamando as APIs do Gerenciador de Membro Virtual

As amostras de código para diversas operações do gerenciador de membro virtual usam os métodos definidos na classe BaseApp. Consulte as amostras de código para obter instruções sobre como fazer chamadas de API.

Para chamar as APIs do gerenciador de membro virtual no código do aplicativo, você deve estar designado a uma das seguintes funções:

  • Função de administrador do WebSphere Application Server.

  • Função do gerenciador de membro virtual designada usando direitos de gerenciamento de repositório associado.

    Para obter mais informações sobre as funções predefinidas do gerenciador de membro virtual, consulte a seção, Mapeando usuários e grupos para funções para designar direitos de gerenciamento de repositório federado, em Fornecendo segurança

    Para obter informações sobre como atribuir usuários ou grupos às funções predefinidas do gerenciador de membros virtuais, leia sobre os comandos mapIdMgrUserToRole, mapIdMgrGroupToRole, removeIdMgrUsersFromRole, removeIdMgrGroupsFromRole, listIdMgrUsersForRoles, e listIdMgrGroupsForRoles no tópico, grupo de comandos IdMgrConfig para o objeto AdminTask na documentação do WebSphere Application Server.

    Para um cenário de exemplo de ponta a ponta, consulte o tópico Código de amostra para usar direitos de gerenciamento de repositório federado.

Código de Compilação

Verifique a configuração do caminho de classe para assegurar-se de que ela inclua os arquivos Java archive (JAR) corretos, para compilar o código.

  • <WAS_HOME>\plugins\com.ibm.ws.runtime.jar
  • <WAS_HOME>\plugins\com.ibm.ws.runtime.wim.base.jar
  • <WAS_HOME>\plugins\org.eclipse.emf.commonj.sdo.jar
  • <WAS_HOME>\lib\j2ee.jar

Código de Execução

Se o código do aplicativo estiver sendo executado no WebSphere Application Server como um aplicativo ou servlet, Assunto e outros parâmetros para acessar as APIs do gerenciador de membro virtual serão usados implicitamente e serão os mesmos do servidor ou processo no qual o aplicativo foi implementado.

Se o aplicativo estiver sendo executado fora do WebSphere Application Server, por exemplo, a partir de um cliente do WebSphere Application Server, use os seguintes argumentos da JVM ao executar o código compilado. Substitua as variáveis mostradas em itálico nos seguintes argumentos pelos valores reais que você precisa.

-Djava.security.auth.login.config=<WAS_HOME>/properties/wsjaas_client.conf 
-Dcom.ibm.CORBA.ConfigURL=<WAS_HOME_URL>/properties/sas.client.props
-Dcom.ibm.SSL.ConfigURL=<WAS_HOME_URL>/properties/ssl.client.props

Use os seguintes argumentos apenas quando você tiver de substituir as credenciais especificadas no arquivo de propriedades CORBA:

-Dcom.ibm.CORBA.loginSource=properties 
-Dcom.ibm.CORBA.loginUserid=AdminUserId 
-Dcom.ibm.CORBA.loginPassword=Admin Password
Alguns exemplos de argumentos da JVM com valores de amostra são fornecidos aqui:
-Djava.security.auth.login.config=C:/Progra~1/IBM/WebSphere/AppClient/properties/wsjaas_client.conf 
-Dcom.ibm.CORBA.ConfigURL=file:/Progra~1/IBM/WebSphere/AppClient/properties/sas.client.props
-Dcom.ibm.SSL.ConfigURL=file:/Progra~1/IBM/WebSphere/AppClient/properties/ssl.client.props 
-Dcom.ibm.CORBA.loginSource=properties
-Dcom.ibm.CORBA.loginUserid=admin
-Dcom.ibm.CORBA.loginPassword=admin
Verifique a configuração do caminho de classe para assegurar-se de que ela inclua os seguintes arquivos JAR antes de tentar executar o código:
  • <WAS_HOME>\lib\j2ee.jar
  • <WAS_HOME>\lib\bootstrap.jar
  • Todos os arquivos JAR em <WAS_HOME>\plugins ..

Estendendo o Esquema de Propriedade

Objetos de dados propertySchema e extensionPropertySchema
O objeto de dados propertySchema é usado para criar um tipo de propriedade e incluí-lo em um tipo de entidade do gerenciador de membro virtual existente em tempo de execução. A nova propriedade é incluída no arquivo wimxmlextension.xml. Entretanto, se você também quiser estender o esquema de banco de dados do repositório de extensão de propriedade, deverá usar o objeto de dados extensionPropertySchema. Se você usar o objeto de dados extensionPropertySchema, a nova propriedade é incluída no tipo de entidade existente no arquivo wimxmlextension.xml bem como armazenada no banco de dados de extensão de propriedade.
Nota: Se você estender uma propriedade em um namespace customizado e, em seguida, usar as APIs get ou search do virtual member manager, deverá mencionar explicitamente o prefixo do namespace junto com o nome da propriedade no gráfico de dados (<nsPrefix>:<propName>). Se uma propriedade com o mesmo nome existir no namespace padrão e no namespace customizado e você criar uma entidade usando esse nome de propriedade, o virtual member manager usará a propriedade no namespace padrão para criar a entidade.
Para código de amostra que usa o objeto de dados propertySchema , consulte Código de amostra para estender o esquema em um repositório LDAP. Para ver o código de amostra que usa o objeto de dados extensionPropertySchema, consulte Código de amostra para estender o esquema no repositório de extensão de propriedade.
Tipos de Dados de Propriedades
A sintaxe dos tipos de dados suportados para propriedades do gerenciador de membro virtual é listada aqui. Para obter mais informações, consulte a seção SchemaConstants das informações de Javadoc do gerenciador de membro virtual na documentação do WebSphere Application Server
  • DATA_TYPE_ANY_SIMPLE_TYPE
  • DATA_TYPE_ANY_URI
  • DATA_TYPE_BASE_64_BINARY
  • DATA_TYPE_BOOLEAN
  • DATA_TYPE_BYTE
  • DATA_TYPE_DATE
  • DATA_TYPE_DATE_TIME
  • DATA_TYPE_DOUBLE
  • DATA_TYPE_IDENTIFIER_TYPE
  • DATA_TYPE_INT
  • DATA_TYPE_LONG
  • DATA_TYPE_SHORT
  • DATA_TYPE_STRING
  • DATA_TYPE_TOKEN