Utilisation d'objets distants

Remonter à Utilisation de types non scalaires dans des interfaces invocables

Utilisez TRemotable comme classe de base pour définir une classe représentant un type de données complexe d'une interface invocable. Par exemple, dans le cas où il vous faut transmettre comme paramètre un enregistrement ou une structure, vous définiriez à la place un descendant de TRemotable dans lequel chaque membre de l'enregistrement ou de la structure est une propriété publiée de votre nouvelle classe.

La fonctionnalité suivante a été dépréciée :

Vous pouvez contrôler si les propriétés publiées de votre descendant de TRemotable apparaissent comme noeuds d'élément ou attributs dans le codage SOAP correspondant du type. Pour transformer la propriété en attribut, utilisez la directive stockée sur la définition de propriété, en affectant la valeur AS_ATTRIBUTE : property MyAttribute: Boolean read FMyAttribute write FMyAttribute stored AS_ATTRIBUTE; __property bool MyAttribute = {read=FMyAttribute, write=FMyAttribute, stored= AS_ATTRIBUTE; Si vous n'incluez pas de directive stockée ou si vous affectez toute autre valeur à la directive stockée (même une fonction qui renvoie AS_ATTRIBUTE), la propriété est codée comme un noeud plutôt que comme un attribut.

La fonctionnalité AS_ATTRIBUTE a été dépréciée. Elle fonctionne toujours pour l'ancien code, mais il est préférable d'utiliser la valeur d'indice d'une propriété. La propriété index vous permet de spécifier si une propriété est un attribut, un élément non lié, un élément facultatif, une valeur texte ou si elle peut prendre la valeur NULL. Le support des éléments facultatifs s'appuie sur l'attribut de propriété stocké, qui pointe sur une méthode renvoyant TRUE si la propriété a été spécifiée, FALSE sinon.

L'exemple suivant illustre le support d'un attribut facultatif et d'un élément texte :

type
{ This stores the languages that the system supports }
  Thumbnail = class(TRemotable)
  private
    FText: WideString;
    FExists: WideString;
    FExists_Specified : boolean;
    procedure SetExists(Index: Integer; _prop_val: WideString);
    function Exists_Specified(Index: Integer): boolean;

  published
    property Text: WideString index IS_TEXT read FText write FText;
    property Exists: WideString index IS_ATTR or IS_OPEN read FExists write SetExists stored Exists_Specified;
  end;

implementation

  procedure Thumbnail.SetExists(Index: Integer; _prop_val: WideString);
  begin
    FExists := _prop_val;
    FExists_Specified := true;
  end;

  function Thumbnail.Exists_Specified(Index: Integer): boolean;
  begin
    Result := FExists_Specified;
  end;
end.

 class Thumbnail : public TRemotable {
 private:
    WideString      FText;
    WideString      FExists;
    bool            FExists_Specified;
    void __fastcall SetExists(int Index, WideString _prop_val)
    {  FExists = _prop_val; FExists_Specified = true;  }
    bool __fastcall Exists_Specified(int Index)
    {  return FExists_Specified;  }
   __published:
    __property WideString       Text = { index=(IS_TEXT), read=FText, write=FText };
    __property WideString     Exists = { index=(IS_ATTR|IS_OPTN), read=FExists, write=SetExists, stored = Exists_Specified };
 };

Si la valeur de votre nouveau descendant de TRemotable représente un type scalaire dans un document WSDL, vous devez utiliser à la place TRemotableXS comme classe de base. TRemotableXS est un descendant de TRemotable qui introduit deux nouvelles méthodes pour assurer la conversion entre votre nouvelle classe et sa représentation sous forme de chaîne. Implémentez ces méthodes en redéfinissant les méthodes XSToNative et NativeToXS.

Pour certains types scalaires XML d'utilisation courante, l'unité XSBuiltIns définit et recense déjà les classes distantes à votre place. Ces types sont listés dans le tableau suivant :

Classes distantes : :

Type XML	Classe distante
dateTime timeInstant	TXSDateTime
date	TXSDate
time	TXSTime
durationtimeDuration	TXSDuration
decimal	TXSDecimal
hexBinary	TXSHexBinary
string	TXSString
boolean	TXSBoolean
entier	TXSInteger
long	TXSLong

Remarque : Vous pouvez utiliser TXSString, TXSBoolean, TXSInteger et TXSLong pour les cas où une chaîne, un booléen, un entier ou une valeur longue peut prendre la valeur nil (NULL ou 0 pour C++). Vous pouvez utiliser le type TXMLData quand les données envoyées ou reçues sont non spécifiées. TXMLData peut être utilisé pour passer du XML brut, comme un schéma, dans un message SOAP.

Après la définition d'une classe distante, celle-ci doit être recensée avec le registre des types distants, comme décrit dans Recensement des types non scalaires. Ce recensement se produit automatiquement sur les serveurs lorsque vous recensez l'interface qui utilise la classe. Côté client, le code permettant de recenser la classe est automatiquement généré lorsque vous importez le document WSDL qui définit le type. Pour un exemple de définition et de recensement d'une classe distante, voir Exemple d'objet distant.

Conseil : Il est judicieux d'implémenter et de recenser les descendants de TRemotable dans une unité distincte du reste de votre application serveur, y compris des unités qui déclarent et recensent les interfaces invocables. De cette manière, vous pouvez utiliser le type pour plusieurs interfaces.

Représentation des attachements

TSoapAttachment constitue un descendant de TRemotable important. Cette classe représente un attachement. Elle peut être utilisée comme valeur d'un paramètre ou valeur de retour d'une méthode sur une interface invocable. Les attachements sont envoyés avec des messages SOAP en tant que parties distinctes d'une fiche multipartie.

Lorsqu'une application de service Web ou le client d'un service Web reçoit un attachement, il (elle) écrit l'attachement dans un fichier temporaire. TSoapAttachment vous permet d'accéder à ce fichier temporaire ou d'enregistrer son contenu dans un flux ou un fichier permanent. Lorsque l'application doit envoyer un attachement, elle crée une instance de TSoapAttachment et attribue son contenu en indiquant le nom d'un fichier et en fournissant un flux à partir duquel lire l'attachement ou une chaîne représentant le contenu de celui-ci.

Gestion de la durée de vie des objets distants

L'un des problèmes qui se posent lors de l'utilisation de descendants de TRemotable concerne les moments de leur création et de leur destruction. Logiquement, l'application serveur doit créer sa propre instance locale de ces objets, car l'instance de l'appelant se trouve dans un espace de processus distinct. Pour gérer cela, les applications de service Web créent un contexte de données pour les requêtes entrantes. Le contexte des données persiste tant que le serveur traite la requête, et il est libéré lorsque tous les paramètres de sortie sont rassemblés dans un message de retour. Lorsque le serveur crée des instances locales d'objets distants, il les ajoute au contexte des données et ces instances sont ensuite libérées avec le contexte des données.

Dans certains cas, vous pouvez préférer empêcher la libération d'une instance d'objet distant après un appel de méthode. Par exemple, si l'objet contient des informations d'état, il peut s'avérer plus efficace d'avoir une seule et même instance pour tous les appels. Pour empêcher la libération de l'objet distant avec le contexte des données, modifiez sa propriété DataContext.

Voir aussi

• Recensement des types non scalaires
• Exemple d'objet distant