Mensajes de solicitud y respuesta

La interfaz XML en Oracle VM Server for SPARC tiene dos formatos diferentes:

• Un formato para enviar comandos a Logical Domains Manager

• Otro formato para que Logical Domains Manager responda sobre el estado del mensaje entrante y las acciones solicitadas en ese mensaje.

Los dos formatos comparten muchas estructuras XML comunes, pero están separados en esta sección para entender mejor las diferencias entre ellos.

Mensajes de solicitud

Una solicitud de XML entrante a Logical Domains Manager en el nivel más básico incluye una descripción de un solo comando que opera en un solo objeto. Las solicitudes más complicadas pueden manejar múltiples comandos y múltiples objetos por comando. El ejemplo siguiente muestra la estructura de un comando XML básico.

<LDM_interface version="1.3">
  <cmd>
    <action>Place command here</action>
    <options>Place options for certain commands here</options>
    <arguments>Place arguments for certain commands here</arguments>
    <data version="3.0">
      <Envelope>
        <References/>
        <!-- Note a <Section> section can be here instead of <Content> -->
        <Content xsi:type="ovf:VirtualSystem_Type" id="Domain name">
          <Section xsi:type="ovf:ResourceAllocationSection_type">
            <Item>
              <rasd:OtherResourceType>LDom Resource Type</rasd:OtherResourceType>
              <gprop:GenericProperty
              key="Property name">Property Value</gprop:GenericProperty>
            </Item>
          </Section>
          <!-- Note: More Sections sections can be placed here -->
        </Content>
      </Envelope>
    </data>
    <!-- Note: More Data sections can be placed here -->
  </cmd>
  <!-- Note: More Commands sections can be placed here -->
</LDM_interface>

Etiqueta <LDM_interface>

Todos los comandos enviados al Logical Domains Manager deben empezar por la etiqueta <LDM_interface>. Cualquier documento enviado al Logical Domains Manager debe tener solo una etiqueta <LDM_interface> contenida en el mismo. La etiqueta <LDM_interface> debe incluir un atributo de versión, como se muestra en el Example 19–1.

La etiqueta <cmd>

En la etiqueta <LDM_interface>, el documento debe contener al menos una etiqueta <cmd>. Cada sección <cmd> debe tener solo una etiqueta <action>. Use la etiqueta <action> para describir qué comando ejecutar. Cada etiqueta <cmd> debe incluir al menos una etiqueta <data> para describir los objetos en los que debe operar el comando.

La etiqueta <cmd> también puede tener una etiqueta <options>, que se usa para las opciones y etiquetas que están asociadas con algunos comandos. Los siguientes comandos usan las opciones:

• El comando ldm remove-domain puede usar la opción –a.

• El comando ldm bind-domain puede usar la opción –f.

• El comando ldm add-vdsdev puede usar la opción –f.

• El comando ldm cancel-operation puede usar la opción migration o reconf.

• El comando ldm add-spconfig puede usar la opción –r autosave-name.

• El comando ldm remove-spconfig puede usar la opción –r.

• El comando ldm list-spconfig puede usar la opción –r [autosave-name].

• El comando ldm stop-domain puede usar las siguientes etiquetas para establecer los argumentos del comando:

  • <force> representa la opción –f.

  • <halt> representa la opción –h.

  • <message> representa la opción –m.

  • <quick> representa la opción –q.

  • <reboot> representa la opción –r.

  • <timeout> representa la opción –t.

  Tenga en cuenta que las etiquetas no deben tener ningún valor de contenido. Sin embargo, las opciones –t y –m deben tener un valor no nulo, por ejemplo, <timeout>10</timeout> o <message>Shutting down now</message>.

En el siguiente fragmento de ejemplo de XML, se muestra cómo pasar una solicitud de reinicio con un mensaje de reinicio al comando ldm stop-domain:

<action>stop-domain</action>
<arguments>
    <reboot/>
    <message>my reboot message</message>
</arguments>

La etiqueta <data>

Cada sección <data> contiene una descripción de un objeto pertinente al comando especificado. El formato de la sección <data> se basa en la porción del esquema XML del borrador de especificación del formato abierto de virtualización (OVF). Este esquema define una sección <Envelope> que contiene una etiqueta <References> (no usada por Oracle VM Server for SPARC) y secciones <Content> y <Section>.

Para Oracle VM Server for SPARC, la sección <Content> se usa para identificar y describir un dominio especial. El nombre de dominio en el id= attribute del nodo <Content> identifica el dominio. En la sección <Content> hay una o varias secciones <Section> que describen los recursos del dominio según lo necesita un comando específico.

Si solo necesita identificar un nombre de dominio, no necesita usar las etiquetas <Section>. Por el contrario, si no se necesita ningún identificador de dominio para el comando, debe incluir una sección <Section, que describa los recursos necesarios para el comando, fuera de la sección <Content, pero dentro de la sección <Envelope.

Una sección <data> no necesita contener una etiqueta <Envelope> en casos donde la información del objeto puede deducirse. Esta situación afecta sobre todo al seguimiento de todos los objetos aplicables a una acción, y a las solicitudes de registro y eliminación del registro de los eventos.

Dos tipos OVF adicionales permiten el uso del esquema de la especificación OVF para definir correctamente todos los tipos de objetos:

• Etiqueta <gprop:GenericProperty>

• Etiqueta <Binding

La etiqueta <gprop:GenericProperty> se maneja cualquier propiedad del objeto para la que la especificación OVF no tiene una definición. El nombre de la propiedad se define en el atributo key= del nodo y el valor de la propiedad son los contenidos del nodo. La etiqueta <binding> se usa en la salida del comando ldm list-bindings para definir los recursos que están enlazados a otros recursos.

Mensajes de respuesta

Una respuesta XML saliente corresponde estrechamente con la estructura de solicitud entrante en términos de los comandos y objetos incluidos, con adición de una sección <Response> para cada objeto y comando especificado, así como una sección general <Response> para la solicitud. Las secciones <Response> proporcionan información sobre el estado y el mensaje. El siguiente ejemplo muestra la estructura de una respuesta a una solicitud XML básica.

<LDM_interface version="1.3">
  <cmd>
    <action>Place command here</action>
    <data version="3.0">
      <Envelope>
        <References/>
        <!-- Note a <Section> section can be here instead of <Content> -->
        <Content xsi:type="ovf:VirtualSystem_Type" id="Domain name">
          <Section xsi:type="ovf:ResourceAllocationSection_type">
            <Item>
              <rasd:OtherResourceType>
                LDom Resource Type
              </rasd:OtherResourceType>
              <gprop:GenericProperty
              key="Property name">
                Property Value
            </gprop:GenericProperty>
            </Item>
          </Section>
          <!-- Note: More <Section> sections can be placed here -->
        </Content>
      </Envelope>
      <response>
        <status>success or failure</status>
        <resp_msg>Reason for failure</resp_msg>
      </response>
    </data>
    <!-- Note: More Data sections can be placed here -->
    <response>
      <status>success or failure</status>
      <resp_msg>Reason for failure</resp_msg>
    </response>
  </cmd>
  <!-- Note: More Command sections can be placed here -->
  <response>
    <status>success or failure</status>
    <resp_msg>Reason for failure</resp_msg>
  </response>
</LDM_interface>

Respuesta general

Esta sección <response>, que es el descendiente directo de la sección <LDM_interface>, indica el éxito o fallo general de toda la solicitud. A menos que el documento XML esté mal formado, la sección <response> incluye solo una etiqueta <status>. Si este estado de respuesta indica un resultado correcto, todos los comandos en todos los objetos se han efectuado correctamente. Si este estado de respuesta es un fallo y no hay etiqueta <resp_msg>, entonces uno de los comandos incluidos en la solicitud original falla. La etiqueta <resp_msg> se usa solo para describir algún problema con el mismo documento XML.

Respuesta de comando

La sección <response> bajo la sección <cmd> alerta al usuario del éxito o fallo de este comando particular. La etiqueta <status> muestra si ese comando se ejecuta correctamente o falla. Como con la respuesta general, si el comando falla, la sección <response> incluye solo una etiqueta <resp_msg> si los contenidos de la sección <cmd> de la solicitud está mal formada. En caso contrario, el estado de fallo significa que uno de los objetos contra el que se ha ejecutado el comando ha provocado un fallo.

Respuesta de objeto

Finalmente, cada sección <data> en la sección <cmd> también tiene una sección <response>. Esta sección muestra si el comando que se ejecuta en este objeto específico es satisfactorio o falla. Si el estado de la respuesta es SUCCESS, no hay etiqueta <resp_msg> en la sección <response>. Si el estado es FAILURE, hay una o más etiquetas <resp_msg en el campo <response, en función de los errores detectados al ejecutar el comando parra ese objeto. Los errores de objeto pueden derivar de problemas detectados cuando se ha ejecutado el comando, o el objeto está mal formado o es desconocido.

Además de la sección <response>, la sección <data> puede contener otra información. Esta información está en el mismo formato que el campo entrante <data>, que describe el objeto que ha provocado el fallo. Consulte La etiqueta <data>. Esta información adicional es especialmente útil en los siguientes casos:

• Cuando un comando falla contra una sección especial <data> pero pasa cualquier sección adicional <data>

• Cuando una sección <data> vacía se pasa en un comando y falla para algunos comandos pero pasa para otros