O Ficheiro serviceconfig.xml

Conteúdos

Nota

Quando este documento remeter para a localização de ficheiros e directórios, o directório <install-home> é aquele em que o pacote Controlador de Agentes foi descompactado.  Este directório também é referido como %TPTP_AC_HOME% nos ficheiros de configuração.

Introdução

O ficheiro serviceconfig.xml é lido pelo Controlador de Agentes para obter definições configuráveis pelo utilizador. É lido uma única vez, no arranque. As modificações a este ficheiro são normalmente restritas, pois quaisquer alterações têm impacto em todos os utilizadores.

O ficheiro serviceconfig.xml contém os seguintes segmentos:

Se a variável do ambiente TPTP_AC_HOME estiver definida, o Controlador de Agentes procura config/serviceconfig.xml relativamente ao caminho por ele definido. De outra forma, procura relativamente à sua própria localização instalada. A localização predefinida do ficheiro serviceconfig.xml é <install-home>/config/serviceconfig.xml.

Cada instância de um Controlador de Agentes que esteja a ser executada no mesmo sistema, requer a sua própria versão serviceconfig.xml com diferentes configurações da camada de transporte. 

Nota

Os Agentes lêem igualmente o ficheiro serviceconfig.xml para obterem as informações do segmento de Ligação, permitindo assim que um Agente comunique com um Controlador de Agentes.  

Os Agentes lêem a respectiva linha de comandos para obterem uma localização alternativa, onde encontrar o ficheiro serviceconfig.xml.  A nome de opção predefinido para especificar a localização é -serviceconfig seguida do nome do caminho do ficheiro de configuração.  Se não for especificado na linha de comandos, o agente procura serviceconfig.xml nas mesmas localizações como descrito acima para o Controlador de Agentes.

Configuração do Controlador de Agentes

A hierarquia dos elementos contidos no ficheiro serviceconfig.xml é apresentada abaixo. A ordem dos elementos apresentados no mesmo nível não é importante. Apenas é esperada uma ocorrência de cada do primeiro nível de elementos (por exemplo, AgentControllerEnvironment, Logging, Agent, Plugin, ProcessController, Connection, ApplicationAliases, PeerConnectionTransport). As hiperligações na hierarquia estabelecem ligações à descrição do elemento formal na secção Elementos e Atributos.

AgentControllerConfiguration
    AgentControllerEnvironment
        Variable
    Logging
    Agent
    Plugin
    ProcessController
    Connection
        TransportLayer
            Configuration
                Port
                PipeName
                MemName
               
SecuredPort
               
FilePort
               
IsDataMultiplexed
                ProcessPolling
               
Jvm
                Version
                SecurityEnabled
                UserDefinition
                Keystore
                KeystorePassword
                Hosts
                   
Allow
                    Deny
    CommandExtractor
    ApplicationAliases
        Application
            Variable
            Parameter
     PeerConnectionTransport

Elementos e Atributos


Elemento:
AgentControllerConfiguration
Este é o elemento raiz da configuração do Controlador de Agentes. As definições são utilizadas pelo Controlador de Agentes quando é iniciado. Apenas pode haver um de cada subelemento.

Subelementos:     AgentControllerEnvironment
                            Logging
                            Agente
                            Plugin
                            ProcessController
                            Connection
                            ApplicationAliases
                            PeerConnectionTransport

Elemento: AgentControllerEnvironment
Define as definições de ambiente globais para todas as aplicações e agentes, lançados através do Controlador de Agentes. Se este elemento for omitido, o ambiente transmitido permanece idêntico ao do próprio Controlador de Agentes. As variáveis definidas aqui não afectam as definições de ambiente do Controlador de Agentes.

Utilizado por: AgentControllerConfiguration

Subelementos: Variable

Elemento: Variable
Este elemento Variable define uma variável de ambiente e a forma como deve ser posicionada no ambiente existente, para formar o ambiente predefinido para todas as aplicações e agentes lançados. Podem ser definidos zero ou mais destes elementos para o AgentControllerEnvironment.

Utilizado por: AgentControllerEnvironment

Atributos:

name
Este valor de cadeia especifica o nome da variável de ambiente.
value
Este valor de cadeia especifica o valor da variável do ambiente.
position
(opcional) Este valor de cadeia é um de "append", "prepend" ou "replace", indicando onde colocar este ambiente relativo ao ambiente predefinido.

Elemento: Logging
Define o nível de gravidade de informação a registar, em que formato e para que localização. Se este elemento for omitido, todos os avisos críticos e graves serão registados, utilizando o formato CBE, no mesmo directório em que o Controlador de Agentes está em execução. Repare que o nome do ficheiro de registo (tptpAgentCtrl.log) não é configurável, apenas a respectiva localização o é.

Utilizado por: AgentControllerConfiguration

Atributos:

level
(opcional) Este valor de cadeia indica o nível de gravidade de mensagens que devem ser registadas. Cada nível inclui-se a si próprio e todos os eventos que sejam mais graves. Especifique um dos seguintes (apresentados em ordem de gravidade crescente):
  • DEBUG - inclui mensagens que fornecem detalhes de baixo nível quanto ao fluxo interno de execução de código do Controlador de Agentes e dos agentes.
  • INFORMATION - inclui eventos que são normais mas podem interessar ao utilizador do programa.
  • WARNING - inclui eventos que são inesperados mas não devem interferir com a operação do programa.
  • CRITICAL - (predefinido) inclui eventos que indicam que a operação normal do programa foi interrompida por um erro.
  • SEVERE - está limitado a eventos que resultem na terminação do programa.
format
(opcional) Este valor de cadeia especifica o formato a utilizar quando se gravarem as mensagens no ficheiro de registo. Especifique uma das seguintes opções:
  • CBE - (predefinido) as mensagens serão gravadas no formato Common Base Event (inclui informações detalhadas quanto ao contexto e origem da mensagem) adequado para consumo por um utilitário de leitura de registo CBE.
  • Simple - as mensagens serão gravadas como texto simples.
directory

(opcional) Este valor de cadeia especifica a localização na qual o ficheiro de registo será criado. O directório predefinido é aquele a partir do qual o Controlador de Agentes é executado.

Elemento: Agent
Este elemento requerido especifica o directório em que os agentes de que o Controlador de Agentes tenha conhecimento terão colocado subdirectórios que identifiquem o agente pelo nome e que contenham um ficheiro de configuração agent.xml com informações quanto ao modo de lançar e gerir o agente.

Utilizado por: AgentControllerConfiguration

Atributos:

path
Este valor de cadeia especifica o nome completo do caminho do directório onde procurar configurações de agentes.

Elemento: Plugin
Este elemento especifica o directório no qual as extensões da configuração do Controlador de Agentes terão sido colocadas.  As extensões são definidas nos ficheiros de configuração pluginconfig.xml.  Os sub-directórios sob o directório especificado também podem conter ficheiros executáveis específicos de extensão.

Utilizado por: AgentControllerConfiguration

Atributos:

path
Este valor de cadeia especifica o nome do caminho completo do directório onde procurar extensões.
Elemento: ProcessController
O elemento ProcessController contém simplesmente um valor que especifica o nome do caminho do executável que o Controlador de Agentes iniciará e posteriormente solicitará para lançar agentes e aplicações. Por predefinição, o Controlador de Agentes iniciará o agente tptpProcessController(.exe) localizado no mesmo directório que o próprio Controlador de Agentes. O executável tem de se registar com o Controlador de Agentes e ser capaz de processar o conjunto de comandos para essa interface. Dado que as respectivas informações de lançamento estão restritas ao nome do caminho aqui contido, não é necessário que este agente tenha especificado um subdirectório de agentes como outros agentes e não pode suportar argumentos da linha de comandos.

Utilizado por: AgentControllerConfiguration

Elemento: Connection
Este elemento é requerido e tem de conter, no mínimo, um elemento TransportLayer, para definir cada um dos seguintes tipos de ligações que são utilizadas pelo Controlador de Agentes: socket, encaminhamento nomeado e memória partilhada.

Utilizado por: AgentControllerEnvironment

Subelementos: TransportLayer

Atributos:

name
Este valor de cadeia fornece um nome para a configuração de ligação.

Elemento: TransportLayer
Este elemento define uma Camada de Transporte que é um componente conectável dentro do Controlador de Agentes responsável pelo envio e recepção de dados entre componentes no sistema, através de um mecanismo de comunicação entre processos.

Utilizado por: Connection

Subelementos:  Configuration
                         CommandExtractor

Atributos:

loadlib
Este valor de cadeia especifica o nome da biblioteca a ser carregada para esta camada de transporte, sem o respectivo sufixo (i.e., não inclui .dll ou .so). É utilizada a pesquisa de caminho de sistema normal para localizar a biblioteca.
type
Este valor de cadeia fornece a identidade específica desta camada de transporte.  Os valores possíveis são: TPTP_SOCKET, TPTP_NAMEDPIPE, TPTP_SHAREDMEM, TPTP_CCTL e TPTP_ACTL.  As camadas de transporte personalizadas utilizarão outros cartões de identificação.  Os valores TPTP_CCTL e TPTP_ACTL são transportes personalizados que fornecem compatibilidade de retrocesso para clientes e agentes que utilizem interfaces de Controlador de Agentes.

Elemento: Configuration
O elemento Configuration contém um subelemento que especifica o mecanismo de comunicação entre processos para cada TransportLayer. Os mecanismos de comunicação disponibilizados para aqui são socket, encaminhamento nomeado, memória partilhada e CCTL.  A camada de transporte ACTL não tem elementos de configuração. As Camadas de Transporte personalizadas poderão ter outros elementos de configuração que são específicos dessas camadas de transporte.

Utilizado por: TransportLayer

Subelementos:     Port (apenas com socketTL e CCTL)
                            PipeName (apenas com namedPipeTL)
                            MemName (apenas com sharedMemTL)
                            SecuredPort (apenas com CCTL)
                            FilePort (apenas com CCTL)
                            IsDataMultiplexed (apenas com CCTL)
                            ProcessPolling (apenas com CCTL)
                            Jvm (apenas com CCTL)
                            Version (apenas com CCTL)
                            SecurityEnabled (apenas com CCTL)
                            UserDefinition (apenas com CCTL e apenas se a segurança estiver activada)
                            Keystore (apenas com CCTL e apenas se a segurança estiver activada)
                            KeystorePassword (apenas com CCTL e apenas se a segurança estiver activada)
                            Hosts (apenas com CCTL)

Elemento: Port
O elemento Port especifica a porta a ser utilizada para comunicação socket. O elemento Port só é válido quando utilizado com as camadas de transporte TPTP_SOCKET e TPTP_CCTL. O respectivo valor inteiro especifica o real número de porta a utilizar para estabelecer a ligação socket.

Utilizado por: Configuration

Elemento: PipeName
O elemento PipeName indica a camada de transporte utilizada para a comunicação de encaminhamento nomeado. O elemento PipeName só é válido quando utilizado com namedPipeTL loadlib. O respectivo valor de cadeia especifica o nome do encaminhamento a utilizar ao estabelecer a ligação.

Utilizado por: Configuration

Elemento: MemName
O elemento MemName indica a camada de transporte utilizada para a comunicação de memória partilhada. O elemento MemName só é válido quando utilizado com sharedMemTL loadlib. O respectivo valor de cadeia especifica o nome do recurso de memória partilhada a utilizar ao estabelecer a ligação.

Utilizado por: Configuration
 

Elemento: SecuredPort
O elemento SecuredPort especifica a porta a ser utilizada para comunicação socket protegida. o elemento SecuredPort só é válido quando utilizado com a camada de transporte TPTP_CCTL. O respectivo valor inteiro especifica o número real de porta a utilizar para estabelecer a ligação socket.

Utilizado por: Configuration

Elemento: FilePort
O elemento FilePort especifica a camada de transporte utilizada para comunicação socket pelo serviço de Transferência de Ficheiros. O elemento FilePort só é válido quando utilizado com a camada de transporte TPTP_CCTL. O respectivo valor inteiro especifica o real número de porta a utilizar para estabelecer a ligação socket.

Utilizado por: Configuration

Elemento: IsDataMultiplexed
O elemento IsDataMultiplexed especifica se devem ser transmitidos os dados de perfilamento e registo através do canal de controlo do Controlador de Agentes. Por predefinição, o canal de dados utiliza uma porta arbitrária para a transmissão de dados e poderá ficar bloqueada com a existência de uma firewall. Transferir os dados através do canal de controlo irá permitir que se abra um conjunto de portas predefinidas para os pedidos de ligação de entrada através de uma firewall. Estas portas incluem a porta predefinida 10002, a porta segura 10003, e a porta do servidor de ficheiros 10005. Este elemento tem um valor Booleano que é predefinido para "FALSE".  O elemento IsDataMultiplexed só é válido quando utilizado com a camada de transporte TPTP_CCTL.

Utilizado por: Configuration

Elemento: ProcessPolling
O elemento ProcessPolling especifica se a execução activa está ou não activada para o estado do processo. Este atributo é utilizado para assegurar que o Controlador de Agentes detecta a conclusão de um processo. Este elemento tem um valor Booleano que é predefinido para "TRUE".  O elemento ProcessPolling só é válido quando utilizado com a camada de transporte TPTP_CCTL.

Utilizado por: Configuration

Elemento: Jvm
O elemento Jvm especifica o caminho totalmente qualificado da biblioteca de tempo de execução dinâmico da Máquina Virtual Java (jvm.dll ou libjvm.so) a ser utilizada pela Transferência de Dados e componentes de ligação protegida. O elemento Jvm só é válido quando utilizado com a camada de transporte TPTP_CCTL.

Utilizado por: Configuration

Elemento: Version
O elemento Version descreve o número de versão do Controlador de Agentes que que será relacionado com outros componentes. O elemento Version só é válido quando utilizado com a camada de transporte TPTP_CCTL.

Utilizado por: Configuration

Elemento: SecurityEnabled
O elemento SecurityEnabled indica se os clientes ligados a esta camada de transporte têm ou não de se ligar à porta protegida.  Se a segurança estiver activada e um cliente tentar ligar-se à porta não protegida, será dado ao cliente o endereço da porta segura e a ligação será recusada.  Este elemento tem um valor Booleano que é predefinido para "FALSE".  O elemento SecurityEnabled só é válido quando utilizado com a camada de transporte TPTP_CCTL.

Utilizado por: Configuration

Elemento: UserDefinition
O elemento UserDefinition descreve quais os utilizadores que se podem ligar a esta camada de transporte.  Se este elemento estiver definido para "ANY", todos os utilizadores que possam ser autenticados com o SO serão autorizados a ligar-se.  Se a segurança estiver activada, será requerido este elemento. Este elemento tem um valor de cadeia que consiste numa lista de nomes de utilizador separada por vírgulas.  O elemento UserDefinition só é válido quando utilizado com a camada de transporte TPTP_CCTL.

Utilizado por: Configuration

Elemento: Keystore
O elemento Keystore especifica a localização do arquivo de chaves para ligações protegidas.  Se a segurança estiver activada, será requerido este elemento. O elemento Keystore só é válido quando utilizado com a camada de transporte TPTP_CCTL.

Utilizado por: Configuration

Elemento: KeystorePassword
O elemento KeystorePassword define a palavra-passe a ser utilizada com o arquivo de chaves para ligações protegidas.  Se a segurança estiver activada, será requerido este elemento. O elemento KeystorePassword só é válido quando utilizado com a camada de transporte TPTP_CCTL.

Utilizado por: Configuration

Elemento: Hosts
O elemento Hosts é utilizado para controlar quais os sistemas centrais que se podem ligar através desta camada de transporte. Este elemento consiste em um ou mais elementos Allow ou Deny.  O elemento Hosts só é válido quando utilizado com a camada de transporte TPTP_CCTL.

Utilizado por: Configuration

Elemento: Allow
O elemento Allow especifica um Sistema central que é autorizado a ligar-se ao Controlador de Agentes através desta camada de transporte.

Utilizado por: Hosts

Atributos:

host
Este nome de cadeia é o nome ou endereço de IP do sistema central. Um valor de "ALL" indica que esta camada de transporte pode aceitar ligações de qualquer sistema central.   Um valor de "LOCAL" indica que as ligações devem ser aceites a partir de processos locais.
net
Este atributo indica uma sub-rede a partir da qual se permitem ligações.
mask
Este atributo indica uma máscara de sub-rede a partir da qual se permitem ligações.

Elemento: Deny
O elemento Deny especifica um Sistema central que não é autorizado a ligar-se ao Controlador de Agentes através desta camada de transporte.

Utilizado por: Hosts

Atributos:

host
Esta cadeia é o nome ou endereço de IP do sistema central a negar.
net
Este atributo indica uma sub-rede a partir da qual se negam as ligações.
mask
Este atributo indica uma máscara de sub-rede a partir da qual se negam ligações.

Elemento: CommandExtractor
Este elemento define um Extractor de Comandos que é um elemento conectável numa Camada de Transporte que extrai comandos da sequência de comunicações entre processos. O respectivo valor de cadeia especifica o nome da biblioteca a ser carregada sem sufixo (i.e., não inclui .dll ou .so) ou prefixo (i.e., "lib" para Linux). É utilizada a pesquisa de caminho de sistema normal para localizar a biblioteca.

Utilizado por: TransportLayer
 

Elemento: ApplicationAliases
O elemento ApplicationAliases é uma lista opcional de definições de nomes alternativos.

Utilizado por: AgentControllerConfiguration

Subelementos: Application

Atributos:

launchAliasesOnly
(opcional) Este atributo de cadeia é "verdadeiro" ou "falso" (predefinido). Se definido para "verdadeiro", apenas as aplicações que tenham sido definidas no âmbito deste elemento serão lançadas. Se o atributo estiver definido para "falso" ou omitido, qualquer aplicação pode ser lançada.

Elemento: Application
O elemento Application define um nome alternativo e informações de lançamento para uma aplicação.

Utilizado por: ApplicationAliases

Subelementos: Variable
Parameter

Atributos:

executable
Este valor de cadeia especifica o nome alternativo para a aplicação executável especificada no atributo de caminho.
location
(opcional) Este valor de cadeia especifica o directório a partir do qual o executável vai ser lançado, algumas vezes referido como o directório de trabalho do executável enquanto este está a ser executado.
path
Este valor de cadeia especifica o nome completo do caminho da aplicação a lançar. Isto é utilizado no lugar do nome alternativo quando se lançar o executável da aplicação.

Elemento: Variable
Este elemento Variable define uma variável do ambiente e a forma como deve ser posicionada no ambiente existente quando a aplicação é lançada. Podem ser definidos zero ou mais destes elementos para uma Application.

Utilizado por: Application

Atributos:

name
Este valor de cadeia especifica o nome da variável de ambiente.
value
Este valor de cadeia especifica o valor da variável do ambiente.
position
(opcional) Este valor de cadeia é um de >"append", "prepend" ou "replace", indicando onde colocar este ambiente relativo ao ambiente predefinido.

Elemento: Parameter
O elemento Parameter define um argumento de linha de comandos a ser dado à aplicação quando lançada. Podem ser definidos zero ou mais destes elementos para uma Application.

Utilizado por: Application

Atributos:

value
Este valor de cadeia especifica um argumento de linha de comandos.
position
(opcional) Este valor de cadeia é um de "append", "prepend" ou "replace" indicando onde colocar este argumento relativo aos argumentos de linha de comandos existentes.

Elemento: PeerConnectionTransport
Este elemento requerido especifica a camada de transporte que será utilizada para estabelecer ligações entre o Controlador de Agentes que lê esta configuração e as instâncias pares do Controlador de Agentes.  O nome valor deste elemento tem de corresponder a um nome de tipo de Camada de Transporte para uma camada de transporte específica declarada na secção Ligação do ficheiro de configuração (por exemplo, TPTP_CCTL).

Utilizado por: AgentControllerConfiguration


Exemplo do Ficheiro serviceconfig.xml

Este exemplo apresenta uma amostra de um ficheiro de configuração de Controlador de Agentes:

<?xml version="1.0" encoding="UTF-8"?>
<AgentControllerConfiguration>
    <AgentControllerEnvironment configuration="default">
        <Variable name="JAVA_PATH" value="C:\Program Files\Java\j2re1.4.2_08\bin\java.exe" position="replace"/>
        <Variable name="RASERVER_HOME" value="C:\Eclipse\Projects\AgentController" position="replace"/>
        <Variable name="TPTP_AC_HOME" value="%RASERVER_HOME%" position="replace"/>
        <Variable name="PLUGINS_HOME" value="%RASERVER_HOME%\plugins" position="replace"/>
        <Variable name="PATH" value="%RASERVER_HOME%\bin" position="prepend"/>
    </AgentControllerEnvironment>
    <ApplicationAliases>
        <Application configuration="default" executable="java.exe" path="%JAVA_PATH%" location="%SYS_TEMP_DIR%">
            <Variable name="CLASSPATH" value="%CLASSPATH_ORG_ECLIPSE_EQUINOX_COMMON%" position="append"/>
            <Variable name="PATH" value="%RASERVER_HOME%\bin" position="prepend"/>
        </Application>
    </ApplicationAliases>
    <Plugin path="%PLUGINS_HOME%"/>
    <Agent path="%TPTP_AC_HOME%\agents"/>
    <Logging level="INFORMATION" format="CBE" directory="%TPTP_AC_HOME%\config"/>
    <ProcessController>%TPTP_AC_HOME%\bin\tptpProcessController.exe</ProcessController>
    <Connection name="Dev">
        <TransportLayer loadlib="socketTL" type="TPTP_SOCKET">
            <Configuration>
                <Port>10006</Port>
            </Configuration>
            <CommandExtractor>tptpCmdExtr</CommandExtractor>
        </TransportLayer>
        <TransportLayer loadlib="namedPipeTL" type="TPTP_LOG">
            <Configuration>
                <PipeName>acmasterlog</PipeName>
            </Configuration>
            <CommandExtractor>tptpCmdExtr</CommandExtractor>
        </TransportLayer>
        <TransportLayer loadlib="namedPipeTL" type="TPTP_NAMEDPIPE">
            <Configuration>
                <PipeName>acmaster</PipeName>
            </Configuration>
            <CommandExtractor>tptpCmdExtr</CommandExtractor>
        </TransportLayer>
        <TransportLayer loadlib="sharedMemTL" type="TPTP_SHAREDMEM">
            <Configuration>
                <MemName>acbuffer</MemName>
            </Configuration>
            <CommandExtractor>tptpCmdExtr</CommandExtractor>
        </TransportLayer>
        <TransportLayer loadlib="tptpCCTL" type="TPTP_CCTL">
            <Configuration>
                <Port>10002</Port>
                <SecuredPort>10003</SecuredPort>
                <FilePort>10005</FilePort>
                <IsDataMultiplexed>false</IsDataMultiplexed>
                <ProcessPolling>true</ProcessPolling>
                <Jvm>C:\Program Files\Java\j2re1.4.2_08\bin\client\jvm.dll</Jvm>
                <Version>4.2.0</Version>
                <SecurityEnabled>true</SecurityEnabled>
                <UserDefinition>ANY</UserDefinition>
                <Keystore>C:\Eclipse\Projects\AgentController\security\tptpSampleKeystore</Keystore>
                <KeystorePassword>password</KeystorePassword>
                <Hosts configuration="default">
                    <Allow host="LOCAL"/>
                </Hosts>
            </Configuration>
            <CommandExtractor>tptpCmdExtr</CommandExtractor>
        </TransportLayer>
        <TransportLayer loadlib="tptpACTL" type="TPTP_ACTL">
            <Configuration/>
            <CommandExtractor>tptpCmdExtr</CommandExtractor>
        </TransportLayer>
    </Connection>
    <PeerConnectionTransport>TPTP_CCTL</PeerConnectionTransport>
</AgentControllerConfiguration>


Copyright (C) 2005, 2006 Intel Corporation.