Fonctions XQuery

Cette fonction est très similaire à la fonction fme:set-attribute, mais elle ajoute à la valeur d'un attribut de caractéristique, plutôt que de remplacer la valeur de l'attribut. Elle comporte deux déclarations :

fme:append-attribute( <attribute name>, <sequence of values> )

fme:append-attribute( <attribute name>, <sequence of values>, <delimiter> )

La valeur sérialisée de la séquence de valeurs sera ajoutée à l'attribut de l'entité. Si la séquence contient plus d'une valeur, les valeurs seront concaténées en une chaîne délimitée avant d'être ajoutées à l'attribut. Le délimiteur par défaut est une virgule, mais le troisième paramètre peut être utilisé pour fournir un délimiteur différent.

Cette fonction ne retourne pas de valeur.

Cette fonction est très semblable à la fonction fme:set-list-attribute mais elle ajoute à la valeur de l'attribut de liste au lieu d'écraser les valeurs existantes. Elle n'a qu'une déclaration.

fme:append-list-attribute( <attribute name>, <sequence of values> )

La fonction sérialise chaque valeur de la séquence dans un élément de l'attribut list. Les valeurs existantes de la liste seront préservées, les nouvelles valeurs étant ajoutées à la fin de la liste.

Cette fonction ne retourne pas de valeur.

Cette fonction récupère la valeur d'un attribut de l'entité courante.  Elle comporte deux déclarations :

fme:get-attribute( <attribute name> )

fme:get-attribute( <attribute name>, <default value> )

Si un deuxième paramètre est fourni et que l'entité n'a pas de valeur pour le nom d'attribut donné, la fonction renvoie simplement la valeur du deuxième paramètre. Le deuxième paramètre peut être n'importe quel type de valeur XQuery : chaîne de caractères, nombre, nœud XML, appel de fonction imbriqué, etc.

Si le deuxième paramètre n'est pas fourni et que l'entité n' a pas de valeur pour l'attribut donné, la fonction retournera simplement une séquence vide.

Les valeurs de chaîne renvoyées par cette fonction seront converties pour être sérialisées dans le contexte dans lequel elles sont utilisées. En particulier, si la valeur est insérée dans un document XML, toute syntaxe XML sera échappée. Par exemple, les caractères < deviendront &lt; et > deviendront &gt;. La fonction fme:get-xml-attribute peut être utilisée pour retourner les nœuds XML. De même, si la valeur est insérée dans un document JSON, elle sera placée entre guillemets et les caractères réservés seront échappés. La fonction fme:get-json-attribute peut être utilisée pour renvoyer des objets ou des tableaux JSON.

Exemples

Considérons une entité avec les attributs suivants :

La fonction fme:get-attribute retourne les résultats suivants :

Cette fonction permet d'accéder au système de coordonnées d'une entité. Si une entité possède un système de coordonnées, la fonction renvoie le nom du système de coordonnées. Si l'entité ne possède pas de système de coordonnées, aucune valeur ne sera renvoyée.

Cette fonction permet de récupérer le contenu d'un attribut de liste dans l'entité actuelle. Elle comporte deux déclarations :

fme:get-list-attribute( <nom de l'attribut> )

fme:get-list-attribute( <nom de l'attribut>, < délimiteur > )

Si aucun paramètre de délimitation n'est fourni, la fonction renvoie l'attribut de liste sous la forme d'une séquence d'éléments individuels. Si un paramètre délimiteur est fourni, la fonction concaténera le contenu de l'attribut de liste en une seule chaîne de caractères, en utilisant la valeur du paramètre délimiteur en tant que délimiteur.

Comme avec la fonction fme:get-attribute, toutes les valeurs de chaîne renvoyées par cette fonction seront converties en chaînes XML ou JSON valides, selon le contexte de l'appel de la fonction. La fonction fme:get-xml-list-attribute peut être utilisée pour retourner une liste de nœuds XML et la fonction fme:get-json-list-attribute peut être utilisée pour retourner des objets ou des tableaux JSON.

Exemples

Considérons une entité avec les attributs suivants :

La fonction fme:get-attribute retourne les résultats suivants :

Cette fonction récupère des attributs contenant des objets ou des tableaux JSON. Elle possède une déclaration :

fme:get-json-attribute( <attribute name> )

Si l'attribut indiqué contient des valeurs JSON, cette fonction parcourra le texte et retournera un objet ou un tableau JSON. Si l'attribut ne contient pas de texte JSON, la fonction renverra une séquence vide.

Exemples

Considérons une entité avec les attributs suivants :

La fonction fme:get-json-attribute retourne les résultats suivants :

Cette fonction est similaire à la fonction fme:get-json-attribute, mais récupère des attributs de liste. Elle n'a qu'une seule déclaration :

fme:get-json-list-attribute( <attribute name> )

La fonction tente d'analyser chaque valeur de l'attribut de la liste dans un objet ou un tableau JSON. Les valeurs qui ne sont pas des objets JSON valides seront ignorées.

Exemples

Considérons une entité avec les attributs suivants :

La fonction fme:get-json-list-attribute peut être utilisée comme ci dessous :

Cette fonction récupère les attributs contenant des nœuds XML. Elle n'a qu'une seule déclaration :

fme:get-xml-attribute( <attribute name> )

Si l'attribut donné contient du texte XML, cette fonction analysera le texte et renverra un nœud XML. Si l'attribut ne contient pas de texte XML, la fonction renverra une séquence vide.

Exemples

Considérons une entité avec les attributs suivants :

La fonction fme:get-xml-attribute retourne les résultats suivants :

Cette fonction est similaire à la fonction fme:get-xml-attribute, mais récupère des attributs de liste. Elle a deux déclarations :

fme:get-xml-list-attribute( <attribute name> )

fme:get-xml-list-attribute( <attribute name>, <delimiter> )

La fonction tente d'analyser chaque valeur de l'attribut de la liste dans un nœud XML. Les valeurs qui ne sont pas des XML valides seront ignorées. Si le paramètre de délimitation est fourni, il sera copié dans la séquence de retour entre chaque valeur XML analysée.

Exemples

Considérons une entité avec les attributs suivants :

The fme:get-xml-list-attribute function may be used as shown below:

Cette fonction renvoie une valeur booléenne (vrai/faux) indiquant si l'un des attributs listées en tant que paramètres existe ou non sur l'entité actuelle. Elle a une déclaration :

fme:has-all-attributes( <attribute names> )

Exemples

Considérons une entité qui a un attribut 'name' et un attribut 'id'.  La fonction fme:has-all-attributes renvoie les résultats suivants :

Cette fonction renvoie une valeur booléenne (vrai/faux) indiquant si l'un des attributs énumérés en tant que paramètres existe ou non sur l'entité actuelle. Elle a une déclaration :

fme:has-any-attributes( <attribute names> )

Exemples

Considérons une entité qui a un attribut 'name' et un attribut 'id'.  La fonction fme:has-any-attributes renvoie les résultats suivants :

Cette fonction est très simple.  Elle renvoie une valeur booléenne (vrai/faux) indiquant si un attribut existe ou non sur l'entité courante.  Elle a une déclaration :

fme:has-attribute( <attribute name> )

Exemples

Considérons une entité qui n'a qu'un seul attribut : 'name'.  La fonction fme:has-attribute renvoie les résultats suivants :

Cette fonction récupère la valeur d'un paramètre publié. Elle n'a qu'une seule déclaration :

fme:parameter-value( <parameter name> )

Exemples

Considérez une liste de paramètres publiés avec les valeurs suivantes :

La fonction fme:parameter-value retourne les résultats suivants :

Cette fonction définit la valeur d'un attribut d'entité. Elle comporte deux déclarations :

fme:set-attribute( <nom de l'attribut>, <séquence de valeurs> )

fme:set-attribute( <nom de l'attribut>, <séquence de valeurs>, <délimiteur> )

L'attribut entité sera défini comme la valeur sérialisée de la séquence de valeurs. Si la séquence contient plus d'une valeur, les valeurs seront concaténées en une chaîne de caractères délimitée, et l'attribut sera défini par cette valeur concaténée. Le délimiteur par défaut est une virgule, mais le troisième paramètre peut être utilisé pour fournir un délimiteur différent.

Cette fonction ne retourne pas de valeur.

Exemples

Le document XML suivant est l'objet contextuel des exemples de cette section.

<country>

<nom>MONTSERRAT</nom>

<area>583.776</area>

<cities>

<city>Plymouth</city>

<city>Brades</city>

</cities>

</country>

Après exécution de la requête suivant :

fme:set-attribute( "name_xml", /country/name ),

fme:set-attribute( "area", /country/area/text() ),

fme:set-attribute( "city_list", /country/cities/city/text() ),

fme:set-attribute( "city_list2", /country/cities/city/text(), "|" )

L'entité a les attributs suivants :

Cette fonction définit la valeur d'un attribut de la liste des entités.  Elle n'a qu'une seule déclaration :

fme:set-list-attribute( <nom de l'attribut>, <séquence de valeurs> )

Cette fonction place chaque valeur de la séquence dans un élément de l'attribut de liste.

Cette fonction ne retourne pas de valeur.

Exemples

Le document XML suivant est l'objet contextuel des exemples de cette section.

<countries>

<country>

<name>Montserrat</name>

<capital>Plymouth</capital>

</country>

<country>

<name>Christmas Island</name>

<capital>The Settlement</capital>

</country>

<country>

<name>Aruba</name>

<capital>Oranjestad</capital>

</country>

</countries>

Après exécution de la requête suivant :

fme:set-list-attribute( "names", /countries/country/name/text() ),

fme:set-list-attribute( "capitals", /countries/country/capital )

L'entité a les attributs suivants :

Cette fonction évalue un modèle, ou un ensemble de modèles, sur les entités qui entrent dans le Transformer par les ports d'entrée correspondants. La fonction renvoie la valeur des sous-modèles qui sont traités. Cette fonction a deux déclarations :

fme:process-features( <template names> )

fme:process-features( <template names>, <attributes to filter>, <filter values> )

Dans les deux cas, le premier paramètre est un nom de modèle, ou une liste de noms de modèles. Si aucun paramètre supplémentaire n'est donné, la fonction exécutera les modèles listés sur toutes les entités qui sont entrées dans le Transformer par les ports d'entrée qui correspondent à ces modèles. Les entités seront traitées dans l'ordre où elles sont arrivées dans le Transformer.

Les deuxième et troisième paramètres peuvent être utilisés pour filtrer les entités à traiter. Le deuxième paramètre doit contenir un nom d'attribut ou une liste de noms d'attributs. Le troisième paramètre doit contenir une valeur d'attribut ou une liste de valeurs. Ces paramètres doivent toujours contenir le même nombre d'éléments. Lorsque la fonction est appelée, elle n'exécute les sous-modèles énumérés que sur les entités qui répondent aux critères suivants :

• L'entité est entrée dans le Transformer via un des ports d'entrée correpondant à l'un de ceux des modèles listés dans le premier paramètre.
• Pour chacun des attributs listés dans le deuxième paramètre, la valeur de l'attribut de l'entité doit correspondre à la valeur de troisième paramètre.

Exemples

L'appel suivant de la fonction exécutera le sous-modèle HOUSE sur toutes les entités qui sont entrées par le port d'entrée HOUSE du Transformer.

fme:process-features( "HOUSE" )

L'appel de fonction suivant exécutera le sous-modèle HOUSE sur toutes les entités qui sont entrées dans le Transformer par le port d'entrée HOUSE, et le sous-modèle BUSINESS sur toutes les entités qui sont entrées par le port d'entrée BUSINESS. Ces entités seront traitées dans l'ordre où elles sont arrivées dans le Transformer.

fme:process-features( ("HOUSE", "BUSINESS" ) )

L'appel suivant de la fonction exécutera le sous-modèle HOUSE sur toutes les entités qui sont entrées par le port d'entrée HOUSE du Transformer et dont num_floors est égal à 3.

fme:process-features( "HOUSE", "num_floors", 3 )

L'appel suivant de la fonction exécutera le sous-modèle HOUSE sur toutes les entités qui sont entrées par le port d'entrée HOUSE du Transformer et dont l'attribut village_id est égal à l'attribut id de l'entité en cours de traitement.

fme:process-features( "HOUSE", "village_id", fme:get-attribute( "id" ) )

L'appel suivant de la fonction exécutera le sous-modèle HOUSE sur toutes les entités qui sont entrées par le port d'entrée HOUSE du Transformer et dont l'attribut num_floors est égal à 3 et dont l'attribut village_id est égal à l'attribut id de l'entité en cours de traitement.

fme:process-features( "HOUSE", ( "num_floors", "village_id" ), ( 3, fme:get-attribute("id") ) )

Cette fonction évalue un modèle, ou un ensemble de modèles. Contrairement à la fonction fme:process-features, elle évaluera le modèle sur la même entité que le modèle qui contient l'appel de fonction en cours d'évaluation. La fonction n'a qu'une seule déclaration :

fme:process-template( <template names> )

Le seul paramètre de cette fonction est un nom de modèle, ou une liste de noms de modèles. Si plus d'un nom est fourni, les modèles seront évalués dans l'ordre dans lequel ils sont listés.

Exemples

L'appel suivant de la fonction exécutera le modèle OWNER.

fme:process-template( "OWNER" )

L'appel suivant de la fonction exécutera les modèle OWNER et ADDRESS.

fme:process-template( ( "OWNER", "ADDRESS" ) )

Cette fonction renvoie des informations sur les géométries en arc. Si la géométrie actuelle n'est pas un arc, la fonction ne renvoie pas de valeur. La fonction a la déclaration suivante :

geom:get-arc-data( <data names> )

La fonction s'attend à ce qu'on lui transmette une liste de chaînes de caractères désignant les données qu'elle doit retourner. La fonction renverra les valeurs sous forme de séquence, dans l'ordre où elles sont énumérées dans l'appel de la fonction. Les noms valides sont :

Exemples

geom:get-arc-data( "sweep-angle" )

geom:get-arc-data( "center-x", "center-y", "center-z" )

Cette fonction retourne la dimension de la géométrie en cours de traitement, sous forme de valeur entière.

Cette fonction renvoie des données sur les géométries d'ellipse. Si la géométrie actuelle n'est pas une ellipse, la fonction ne renvoie pas de valeur. La fonction a la déclaration suivante :

geom:get-ellipse-data( <data names> )

La fonction s'attend à ce qu'on lui transmette une liste de chaînes de caractères désignant les données qu'elle doit retourner. La fonction renverra les valeurs sous forme de séquence, dans l'ordre où elles sont énumérées dans l'appel de la fonction. Les noms valides sont :

Exemples

geom:get-ellipse-data( "primary-radius", "secondary-radius" )

geom:get-ellipse-data( "rotation" )

Ces fonctions renvoient les valeurs x/y/z du point final des géométries linéaires, telles que les lignes, les arcs et les trajectoires. Si la géométrie est un point, ces fonctions renvoient les valeurs x/y/z de la géométrie du point. Ces fonctions ne renvoient aucune valeur pour tout autre type de géométrie.

Cette fonction renvoie le nom de la géométrie en cours de traitement. Si la géométrie n'a pas de nom, cette fonction ne renvoie pas de valeur.

Cette fonction renvoie une chaîne contenant les valeurs de tous les points de la géométrie en cours de traitement. Pour les géométries courbes, telles que les ellipses et les arcs, les points de la version stroboscopique seront utilisés. Cette fonction comporte trois déclarations :

geom:get-points()

geom:get-points( <axis-order> )

geom:get-points( <axis-order>, <axis-separator>, <point-separator> )

Le paramètre d'ordre des axes est une chaîne de caractères, indiquant l'ordre dans lequel les coordonnées x, y et z doivent apparaître dans la chaîne. Si le paramètre n'est pas donné, l'ordre "xyz" est utilisé. Le deuxième paramètre indique le délimiteur qui doit être utilisé entre les valeurs x, y et z d'un point, tandis que le troisième paramètre indique le délimiteur qui doit être utilisé entre chaque point. Le délimiteur d'axe par défaut est une virgule, et le délimiteur de point par défaut est un espace.

Exemples

geom:get-points( "xy" )

geom:get-points( "yxz" )

geom:get-points( "yx", "/", " " )

geom:get-points( "xyz", " ", "," )

Le dernier exemple inverse les séparateurs par défaut des axes et des points avec un espace entre les axes et une virgule entre chaque point.

Ces fonctions renvoient les valeurs x/y/z du point final des géométries linéaires, telles que les lignes, les arcs et les trajectoires. Si la géométrie est un point, ces fonctions renvoient les valeurs x/y/z de la géométrie du point. Ces fonctions ne renvoient aucune valeur pour tout autre type de géométrie.

Cette fonction renvoie des informations sur les géométries de texte. Si la géométrie actuelle n'est pas une géométrie de texte, la fonction ne renvoie pas de valeur. La fonction a la déclaration suivante :

geom:get-text-data( <data names> )

La fonction s'attend à ce qu'on lui transmette une liste de chaînes de caractères désignant les données qu'elle doit retourner. La fonction renverra les valeurs sous forme de séquence, dans l'ordre où elles sont énumérées dans l'appel de la fonction. Les noms valides sont :

Exemples

geom:get-text-data( "rotation" )

geom:get-text-data( "size", "string" )

Cette fonction est presque identique à la fonction fme:get-attribute. Elle renvoie la valeur d'un trait sur la géométrie en cours de traitement. Elle comporte deux déclarations :

geom:get-trait( <trait name> )

geom:get-trait( <trait name>, <default value> )

Si un deuxième paramètre est fourni, et que la géométrie n'a pas de valeur pour le trait donné, la fonction renverra simplement la valeur du deuxième paramètre. Le deuxième paramètre peut être n'importe quel type de valeur XQuery : chaîne de caractères, nombre, nœud XML, appel de fonction imbriqué, etc.

Si un deuxième paramètre n'est pas fourni, et que la géométrie n'a pas de valeur pour le trait demandé, la fonction ne retournera pas de valeur.

Ces fonctions renvoient les valeurs x/y/z d'une géométrie ponctuelle. Elles ne renverront pas de valeur si elles sont exécutées sur une géométrie non ponctuelle.

Exemples :

{

"x" : geom:get-x-coord(),

"y" : geom:get-y-coord(),

"z" : geom:get-z-coord()

}

<point x="geom:get-x-coord()" y="geom:get-y-coord()" z="geom:get-z-coord()" />

Cette fonction évalue un sous-modèle, en fonction du type de géométrie en cours de traitement. Cela permet d'exécuter un sous-modèle différent pour chaque type de géométrie. Cette fonction a la déclaration suivante :

geom:process-geometry( <conf/> )

Comme décrit ci-dessus, le paramètre conf ou le trait geometry_template indiquera quel modèle exécuter pour chaque type de géométrie.

Exemples

geom:process-geometry( <conf line="ROAD" point="POI" polygon="PARCEL" /> )

Si la géométrie en cours de traitement est une collection (un agrégat ou une géométrie multiple), cette fonction évalue un sous-modèle pour chaque partie de la collection. Les géométries individuelles seront traitées dans l'ordre où elles apparaissent dans la collection, et un sous-modèle sera choisi en fonction du type de la géométrie. Cette fonction peut être utilisée pour évaluer un modèle de manière récursive, par exemple si une géométrie agrégée contient une autre géométrie agrégée. Comme les autres fonctions de cette section, cette fonction prend comme paramètre un élément conf, qui indique les modèles à exécuter pour les différents types de géométrie.

Cette fonction peut également être utilisée pour évaluer des sous-modèles sur les parties de géométries qui ne sont pas typiquement considérées comme des collections. Par exemple, si la géométrie traitée est un chemin, cette fonction peut être utilisée pour évaluer un sous-modèle sur chaque segment du chemin. De même, si la géométrie en cours est un beignet, cette fonction peut être utilisée pour évaluer un sous-modèle sur chaque limite intérieure du beignet.

Cette fonction ne retourne rien si la géométrie en cours de traitement n'est pas une géométrie de type collection, chemin ou polygone troué.

Exemples

geom:process-parts( <conf area="PARCEL" curve="ROAD" /> )

Cette fonction évalue un sous-modèle sur tous les points qui composent la géométrie en cours de traitement. Par exemple, si la géométrie actuelle est une ligne, la fonction évalue un sous-modèle sur chaque sommet de la ligne. Si la géométrie actuelle est un polygone, la fonction évaluera un sous-modèle sur chaque sommet de la limite du polygone. Les arcs et les ellipses seront traits, et un sous-modèle sera évalué sur chaque point de la ligne ou du polygone traits. Cette fonction n'a qu'une seule déclaration ; contrairement aux autres fonctions de cette section, elle ne prend pas d'élément conf, mais un seul paramètre de type chaîne.

geom:process-points( <sub-template name> )

Exemples

geom:process-points( "WAYPOINT" )

geom:process-boundary

Si la géométrie traitée est une zone, cette fonction peut être utilisée pour évaluer un sous-modèle sur la limite de la zone. Cette fonction s'applique uniquement aux géométries de type polygone, polygone troué et ellipse. Elle a la déclaration suivante.

geom:process-boundary( <conf line="" arc="" path="" /> )

Comme la limite d'une zone sera toujours une ligne, un arc ou un chemin, ce sont les seuls attributs de conf qui sont utilisés par la fonction, avec les attributs plus génériques 'curve' et 'all'. La fonction geom:process-parts peut être utilisée pour évaluer un sous-modèle pour chaque limite intérieure d'un polygone troué.