Messages de demande et de réponse

L'interface XML d'Oracle VM Server for SPARC a deux formats différents :

• Un format pour envoyer des commandes dans Logical Domains Manager

• Un autre format pour que Logical Domains Manager réponde sur l'état du message entrant et les actions demandées dans le message.

Ces deux formats partagent de nombreuses structures XML communes, mais sont séparés dans cette présentation pour une meilleure compréhension de leurs différences.

Messages de demande

Une demande XML entrante vers Logical Domains Manager à son niveau le plus basique comprend une description d'une seule commande, s'appliquant à un seul objet. Les demandes plus complexes peuvent traiter plusieurs commandes et plusieurs objets par commande. L'exemple suivant présente la structure d'une commande XML de base.

<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>

Balise <LDM_interface>

Toutes les commandes envoyées à Logical Domains Manager doivent commencer par la balise <LDM_interface>. Tout document envoyé à Logical Domains Manager doit comporter une balise unique <LDM_interface> contenue dedans. La balise <LDM_interface> doit inclure un attribut de version comme indiqué dans l'Example 19–1.

Balise <cmd>

Dans la balise <LDM_interface>, le document doit inclure au moins une balise <cmd>. Chaque section <cmd> doit comporter uniquement une seule balise <action>. Utilisez la balise <action> pour décrire la commande à exécuter. Chaque balise <cmd> doit inclure au moins une balise <data> pour décrire les objets sur lesquels la commande doit être appliquée.

La balise <cmd> peut également avoir une balise <options>, qui est utilisée pour les options et les indicateurs associés à certaines commandes. Les commandes suivantes utilisent des options :

• La commande ldm remove-domain peut utiliser l'option –a.

• La commande ldm bind-domain peut utiliser l'option –f.

• La commande ldm add-vdsdev peut utiliser l'option –f.

• La commande ldm cancel-operation peut utiliser l'option migration ou reconf.

• La commande ldm add-spconfig peut utiliser l'option –r autosave-name.

• La commande ldm remove-spconfig peut utiliser l'option –r.

• La commande ldm list-spconfig peut utiliser l'option –r [autosave-name].

• La commande ldm stop-domain peut utiliser les balises suivantes pour définir les arguments de commande :

  • <force> correspond à l'option –f.

  • <halt> correspond à l'option –h.

  • <message> correspond à l'option –m.

  • <quick> correspond à l'option –q.

  • <reboot> correspond à l'option –r.

  • <timeout> correspond à l'option –t.

  Notez que les balises ne doivent avoir aucune valeur de contenu. Toutefois, les options –t et –m doivent avoir une valeur non nulle, par exemple, <timeout>10</timeout> ou <message>Shutting down now</message>.

L'extrait d'exemple XML suivant indique comment envoyer une demande de réinitialisation accompagnée d'un message de réinitialisation à la sous-commande ldm stop-domain :

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

Balise <data>

Chaque section <data> contient une description d'un objet correspondant à la commande indiquée. Le format de la section <data> repose sur la portion de schéma XML de la spécification préliminaire OVF (Open Virtualization Format). Le schéma définit une section <Envelope> qui contient une balise <References> (non utilisée par Oracle VM Server for SPARC) et des sections <Content> et <Section>.

Pour Oracle VM Server for SPARC, la section <Content> est utilisée pour identifier et décrire un domaine particulier. Le nom de domaine dans l'attribut id= du noeud <content> identifie le domaine. Dans la section <Content>, il y a une ou plusieurs sections <Section> décrivant les ressources du domaine comme requis par la commande spécifique.

Si vous devez uniquement identifier un nom de domaine, il est alors inutile d'utiliser des balises <Section>. Inversement, si aucun identifiant de domaine n'est nécessaire pour la commande, vous devez alors fournir une section <Section> décrivant les ressources nécessaires à la commande, en dehors de la section <Content>, mais toujours dans la section <Envelope>.

Une section <data> ne doit pas contenir une balise <Envelope> si les informations de l'objet peuvent être induites. Cette situation s'applique principalement aux demandes de surveillance de tous les objets applicables à une action, à l'enregistrement des événements et aux demandes d'annulation d'enregistrement.

Deux types OVF supplémentaires permettent d'utiliser le schéma de spécification OVF afin de définir correctement tous les types d'objets :

• Balise <gprop:GenericProperty>

• Balise <Binding>

La balise <gprop:GenericProperty> a été définie pour traiter n'importe quelle propriété d'objet pour laquelle la spécification OVF n'a pas de définition. Le nom de la propriété est défini dans l'attribut key= du noeud et la valeur de la propriété est le contenu du noeud. La balise <binding> est utilisée dans la sortie de commande ldm list-bindings pour définir les ressources liées à d'autres ressources.

Messages de réponse

Une réponse XML sortante correspond étroitement à la structure de la demande entrante en termes de commandes et d'objets inclus, en ajoutant une section <Response> pour chaque objet et commande indiqué, ainsi qu'une section globale <Response> pour la demande. Les sections <Response> fournissent des informations d'état et de message. L'exemple suivant présente la structure de la réponse à une demande XML de base.

<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>

Réponse globale

Cette section <response>, qui est l'enfant direct de la section <LDM_interface>, indique le succès ou l'échec global de toute la demande. A moins que le document XML entrant ne sont pas correctement formé, la section <response> comprend uniquement une balise <status>. Si l'état de la réponse indique un succès, toutes les commandes sur tous les objets ont abouti. Si l'état de cette réponse est un échec et qu'il n'y a pas de balise <resp_msg>, cela signifie que l'une des commandes incluses dans la demande d'origine a échoué. La balise <resp_msg> est uniquement utilisée pour décrire certains problèmes liés au document XML lui-même.

Réponse de la commande

La section <response> sous la section <cmd> alerte l'utilisateur du succès ou de l'échec de cette commande en particulier. La balise <status> indique si cette commande a abouti ou échoué. Tout comme pour la réponse globale, si la commande échoue, la section <response> comprend uniquement une balise <resp_msg> si le contenu de la section <cmd> de la demande n'est pas correctement formé. Sinon, l'état d'échec signifie qu'un des objets sur lesquels la commande a été exécutée a provoqué une erreur.

Réponse de l'objet

Enfin, la section <data> d'une section <cmd> comporte également une section <response>. Cette section indique si la commande en cours d'exécution sur l'objet concerné aboutit ou échoue. Si l'état de la réponse est SUCCESS, il n'y a pas de balise <resp_msg> dans la section <response>. Si l'état est FAILURE, il existe une ou plusieurs balises <resp_msg> dans la zone <response>, en fonction des erreurs rencontrées lors de l'exécution de la commande sur cet objet. Les erreurs des objets peuvent provenir de problèmes détectés lors de l'exécution de la commande ou d'un objet mal formé ou inconnu.

En plus de la section <response>, la section <data> peut contenir d'autres informations. Ces informations sont dans le même format qu'une zone <data> entrante, décrivant l'objet qui a provoqué l'erreur. Voir la section Balise <data>. Ces informations supplémentaires sont surtout utiles dans les cas suivants :

• Lorsqu'une commande échoue sur une section <data> spécifique mais aboutit pour d'autres sections <data>

• Lorsqu'une section <data> est transmise dans une commande et échoue pour certains domaines, mais aboutit pour d'autres