Proposition de mise à jour du wsdl

[dlevasseuraltitude]

Voir Readme.md avec patchnote

[aminvielledebat]

Hello !
Cool pour la proposition.
Pour ce qui est du README, on fonctionnerait comment du coup ? Chaque PR porte sa modif, ou on le fait au moment du tag ?

[aminvielledebat]

Closes #2 #1

[aminvielledebat]

Côté Orange, après une première relecture un peu plus poussée, on constate qu'il y a encore des points bloquants :

• Pas conforme à la spécification interop' sur le format des champs
• Trop lié à Microsoft => problème d’interopérabilité potentiel.
• Erreur un une liste d'objets qui ne décrit pas une collection
• Erreurs avec plusieurs outils de génération empêchant les autres ORTs de travailler sur un pied d'égalité.

Si besoin, n'hésitez pas à revenir vers nous.

[aminvielledebat]

Je ne veux pas dire de bétise, mais de mémoire ce namespace n'existe pas, c'est juste une convention pour WCF (.NET).

[aminvielledebat]

Il faudrait spécifier le Data Contract Namespace en précisant un domaine intérop plutôt.
D'ailleurs pourquoi utiliser les WCF pour un wsdl qui doit être multi language ?

De ce que j'ai vu/lu (sauf erreur, car je ne maitrise pas trop WCF) ce n'est jamais évident d'utiliser ça pour certains langage et c'est très orienté .NET... soit pas du tout interopérable.

[aminvielledebat]

Il manque toujours le versionning de namespace qui est super important.
J'ai fait une PR dans ce sens. Tu peux t'appuyer dessus ou la valider et merge/rebase ton travail (~5mins max).

[dlevasseuraltitude]

Ok j'ajoute cette modification dans le fichier WSDL

[aminvielledebat]

Super ! Merci beaucoup :).
Si tu as besoin d'aide, j'en remets une couche, mais nous pouvons vous aider sur le sujet.

[aminvielledebat]

Pourquoi ne pas avoir ajouté une longueur max comme tu l'avais souhaité au départ ?
Je rappelle l'ancien code :

<xs:element minOccurs="0" maxLength="20" name="ReferenceCommandePriseInterneOC" nillable="true"
            type="xs:string"/>
<xs:element minOccurs="0" maxLength="20" name="ReferencePrestationPrise" nillable="true"
            type="xs:string"/>

La perte de la longueur max risque de nous amener les mêmes problèmes qu'avec les fichiers interop', à savoir une gestion spécifique par ORTs.
De plus c'est décrit explicitement dans la spécification Word. Il faut donc l'implémenter.

De notre côté, on peut vous aider sur le sujet, mais il faut se mettre d'accord.

[dlevasseuraltitude]

Alors de notre côté, en le passant dans un validateur, ces éléments étaient retournées comme étant en erreur. Je vais me pencher là dessus voir si j'ai un moyen de les intégrer sans erreur.

[aminvielledebat]

Je te confirme, l'attribute maxLength n'est pas conforme. Il faut utiliser des restrictions en définissant les différents types de la façon suivante :

<xsd:simpleType name="TonTypeQuiVaBien">
        <xsd:restriction base="xsd:string">
            <xsd:minLength value="LeMinDeCars"/>
            <xsd:maxLength value="LeMaxDeCars"/>
        </xsd:restriction>
    </xsd:simpleType>

Bon par contre, c'est clair que c'est long et fastidieux :-(

[dlevasseuraltitude]

Ok merci pour l'info, je regarde de mon côté pour intégrer ces restrictions

[dlevasseuraltitude]

Par exemple ça donnerai ça pour l'élément "ReferenceCommandePriseInterneOC" tu confirmes?

<xs:element minOccurs="0" name="ReferenceCommandePriseInterneOC" nillable="true" type="xs:string">
        <xs:simpleType>
	        <xs:restriction base="xs:string">
		        <xs:minLength value="0"/>
		        <xs:maxLength value="20"/>
	        </xs:restriction>
        </xs:simpleType>
</xs:element>

[jlsaxione]

juste pour info, le client ne se génère pas du tout en java. j'attends la prochaine version.
Est il possible d'avoir accès au repo personnel ?juste pour tenter de générer avec les évolutions ?

[jlsaxione]

Cette référence d'un point de vue fonctionnel est elle obligatoire ? dans la pdc elle l'est.
dans ce cas le minLength à 0 et le nillable true me gène.

[aminvielledebat]

Pour l'accès à la version en cours, je suis du même avis que @jlsaxione.
Le plus simple serait que vous pushiez sur une branche à vous sur ce repo. Cela nous permettrait au passage de pouvoir se baser pour nos PRs (ex avec la mienne sur la pagination, où je vais devoir faire un rebase suite à votre merge).

[jlsaxione]

bon avec un plugin maven cxf le code se génère, en revanche le code généré est loin d'être propre.
Je rejoins Alexis sur le sujet des encapsulations org.datacontract et com.microsoft.

[aminvielledebat]

Géré dans la #21

[aminvielledebat]

Idem et sur tous les autres pour lesquels vous avez supprimé le contrôle de longueur.

[dlevasseuraltitude]

Idem que mon commentaire précédent

[aminvielledebat]

Il manque le maxOccurs, sinon ta collection ne fera qu'un seul élément.

[dlevasseuraltitude]

Bien vu, mais lors d'une mise à jour de route optique, n'est-on pas censé retourner une seule route optique. Dans quels cas peut-on en remonter plusieurs? Pour nous il s'agit d'une erreur dans la documentation

[aminvielledebat]

De ce que j'ai cru comprendre dans la doc, on parle de 1 à 4 fibres en fonction du type d'ingénierie, comme dans le Cr ou la Notif de Reprov.
En phase avec toi sur le peu d'utilité de l'information. C'est quelque chose que nous avons déjà fait remonter plusieurs fois en interop'.

[dlevasseuraltitude]

Effectivement en relisant la doc le type ListeRouteOptique retourne jusqu'à quatre routes, je vais donc faire la modification, par contre lorsque l'on met à jour une route, on réserve une seule fibre, qui pour moi ne correspond forcément qu'à une seule route. Il faudrait en rediscuter en groupe interop car pour moi retourner plus d'une route n'a pas sens.

[aminvielledebat]

Complètement en phase ! Mais c'est comme le Cr et la NotifReprov...

[aminvielledebat]

👍

[aminvielledebat]

Je ne comprends pas à quoi sert ce niveau d'encapsulation supplémentaire. Peux-tu nous expliquer ?

Selon moi, il faudrait mieux le supprimer si il ne sert pas.
i.e :

• Pour les objets requêtes, tu crées systématiquement un élément demande, qui plus est nillable qui n'a pas lieu d'être (à quoi sert-il ? ou alors je n'ai pas compris).
• Pour les objets réponses, même chose avec un sous élément NomOperation**Result**, et même remarque sur le fait qu'il soit nillable.

[dlevasseuraltitude]

Je suis d'accord concernant le nillable, qui n'a pas d'intérêt ici. Pour moi cette encapsulation sert à faire le lien entre la méthode et le type complexe passé en paramètre dans le cas de la demande, et le type complexe de retour dans le cas de la réponse.

[aminvielledebat]

Tu pourras m'expliquer pour l'encapsulation ? Au pire on peut s'appeler.
Comme ça, je dirai que le seul avantage est de permettre le pattern middleware, mais à part ça 😕 ... normalement tu peux mapper directement, sans avoir à ajouter ce niveau supplémentaire.

Avec les exemples qui vont bien. Avec tes définitions, ma requête de base donne ça :

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:int="http://interop-fibre.fr/" xmlns:ns="http://schemas.datacontract.org/2004/07/">
   <soapenv:Header>
      </soapenv:Header>
   <soapenv:Body>
      <int:RecherchePBO>
         <!--Optional:-->
         <int:demande>
            <ns:Entete>
               <ns:HorodatageRequete>?</ns:HorodatageRequete>
               <ns:OperateurCommercial>
                  <!--Optional:-->
                  <ns:Identifiant>?</ns:Identifiant>
                  <ns:Nom>?</ns:Nom>
               </ns:OperateurCommercial>
               <ns:VersionWS>?</ns:VersionWS>
            </ns:Entete>
            <!--Optional:-->
            <ns:ReferenceCommandePriseInterneOC>?</ns:ReferenceCommandePriseInterneOC>
            <!--Optional:-->
            <ns:ReferencePrestationPrise>?</ns:ReferencePrestationPrise>
         </int:demande>
      </int:RecherchePBO>
   </soapenv:Body>
</soapenv:Envelope>

Alors que dans mon esprit, on était plus censé avoir :

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:int="http://interop-fibre.fr/" xmlns:ns="http://schemas.datacontract.org/2004/07/">
   <soapenv:Header>
      </soapenv:Header>
   <soapenv:Body>
      <int:RecherchePBO>
            <ns:Entete>
               <ns:HorodatageRequete>?</ns:HorodatageRequete>
               <ns:OperateurCommercial>
                  <!--Optional:-->
                  <ns:Identifiant>?</ns:Identifiant>
                  <ns:Nom>?</ns:Nom>
               </ns:OperateurCommercial>
               <ns:VersionWS>?</ns:VersionWS>
            </ns:Entete>
            <!--Optional:-->
            <ns:ReferenceCommandePriseInterneOC>?</ns:ReferenceCommandePriseInterneOC>
            <!--Optional:-->
            <ns:ReferencePrestationPrise>?</ns:ReferencePrestationPrise>
      </int:RecherchePBO>
   </soapenv:Body>
</soapenv:Envelope>

[dlevasseuraltitude]

Effectivement, sans cette encapsulation ça marche aussi, donc je vais l'enlever du wsdl

[aminvielledebat]

Top ! Merci 👍

[aminvielledebat]

Cool ! En voilà une bonne nouvelle 😄

Pour cette histoire de nommage, je sais qu'en termes de best-practices chez nous, on fait comme tu l'as décrit à savoir NomOperation = NomElementRequete et pour la réponse, idem mais avec Response à la fin.
Personnellement, je ne ferai pas une jaunisse si ça change, mais je pars du principe que cela fait partie de l'implémentation, sauf si on vient nous dire qu'il faut absolument respecter ce qui est défini dans la spec... et dans ce cas, ton encapsulation ne respecte pas non plus le document 😃

[dlevasseuraltitude]

OK Merci du coup de main :)

Par contre, pourquoi la version avec encapsulation ne respecterai pas le document? Au niveau des type etc... tout me semblait OK

[aminvielledebat]

Regarde les signatures, c'est plus simple :

La version avec encapsulation :

public function RecherchePBO(RecherchePBO $parameters): RecherchePBOResponse;

Avec :

class RecherchePBO
{
    /**
     * @var RecherchePBODemande $demande
     */
    protected $demande = null;
...
}

class RecherchePBODemande
{

    /**
     * @var EnteteRequeteType $Entete
     */
    protected $Entete = null;

    /**
     * @var ReferenceCommandePriseInterneOC $ReferenceCommandePriseInterneOC
     */
    protected $ReferenceCommandePriseInterneOC = null;

    /**
     * @var ReferencePrestationPrise $ReferencePrestationPrise
     */
    protected $ReferencePrestationPrise = null;

...
}

Le xml associé :

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://interop-fibre.fr/Emutation/1.0/">
   <soapenv:Header/>
   <soapenv:Body>
      <ns:ConsultationFibres>
         <!--Optional:-->
         <ns:demande>
            <ns:Entete>
               <ns:HorodatageRequete>?</ns:HorodatageRequete>
...

La version sans encapsulation :

public function RecherchePBO(RecherchePBO $request): RecherchePBOResponse;

Avec :

class RecherchePBO
{

    /**
     * @var EnteteRequeteType $Entete
     */
    protected $Entete = null;

    /**
     * @var ReferenceCommandePriseInterneOC $ReferenceCommandePriseInterneOC
     */
    protected $ReferenceCommandePriseInterneOC = null;

    /**
     * @var ReferencePrestationPrise $ReferencePrestationPrise
     */
    protected $ReferencePrestationPrise = null;
...
}

Le xml associé :

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://interop-fibre.fr/Emutation/1.0/">
   <soapenv:Header/>
   <soapenv:Body>
      <ns:RecherchePBO>
         <ns:Entete>
            <ns:HorodatageRequete>?</ns:HorodatageRequete>
...

La spec qui va bien :

[aminvielledebat]

Dans le même sens si on pousse le bouchon, la réponse ne respecte pas la spec non plus :

Le wsdl :

            <xsd:element name="RecherchePBOResponse">
                <xsd:complexType>
                    <xsd:sequence>
                        <xsd:element name="CodeRetour" nillable="true" type="tns:CodeRetourType"/>
                        <xsd:element name="Entete" nillable="true" type="tns:EnteteReponseType"/>
                        <xsd:element name="ListePBO" nillable="true" type="tns:ListePboType"/>
                    </xsd:sequence>
                </xsd:complexType>
            </xsd:element>

La spec :

On voit bien un delta sur l'ordre des paramètres ainsi que sur la case de ListePBO... mais je pense que l'on peut dire que c'est de l'implémentation non ou on va juste qu'au bout du bout ?

[aminvielledebat]

Géré dans la #21

[aminvielledebat]

Techno microsoft ici encore. A supprimer en interop' selon moi.

[aminvielledebat]

L'élément Entete de devrait pas être dans le header Soap ?

Du style passer de ce format :

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:int="http://interop-fibre.fr/" xmlns:ns="http://schemas.datacontract.org/2004/07/">
   <soapenv:Header>
      </soapenv:Header>
   <soapenv:Body>
      <int:RecherchePBO>
            <ns:Entete>
               <ns:HorodatageRequete>?</ns:HorodatageRequete>
               <ns:OperateurCommercial>
                  <!--Optional:-->
                  <ns:Identifiant>?</ns:Identifiant>
                  <ns:Nom>?</ns:Nom>
               </ns:OperateurCommercial>
               <ns:VersionWS>?</ns:VersionWS>
            </ns:Entete>
            <!--Optional:-->
            <ns:ReferenceCommandePriseInterneOC>?</ns:ReferenceCommandePriseInterneOC>
            <!--Optional:-->
            <ns:ReferencePrestationPrise>?</ns:ReferencePrestationPrise>
      </int:RecherchePBO>
   </soapenv:Body>
</soapenv:Envelope>

A ce format :

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:int="http://interop-fibre.fr/" xmlns:ns="http://schemas.datacontract.org/2004/07/">
   <soapenv:Header>
      <int:EnteteRequeteType>
         <int:HorodatageRequete>?</int:HorodatageRequete>
         <int:OperateurCommercial>
            <!--Optional:-->
            <int:Identifiant>?</int:Identifiant>
            <int:Nom>?</int:Nom>
         </int:OperateurCommercial>
         <int:VersionWS>?</int:VersionWS>
      </int:EnteteRequeteType>
   </soapenv:Header>
   <soapenv:Body>
      <int:RecherchePBODemande>
         <!--Optional:-->
         <int:ReferenceCommandePriseInterneOC>?</int:ReferenceCommandePriseInterneOC>
         <!--Optional:-->
         <int:ReferencePrestationPrise>?</int:ReferencePrestationPrise>
      </int:RecherchePBODemande>
   </soapenv:Body>
</soapenv:Envelope>

[dlevasseuraltitude]

De notre côté on a pas l'habitude de gérer ça de cette manière. Cet élément EnteteRequeteType est un paramètre de la méthode RecherchePBO. De plus, en déplaçant cet entête, je ne suis pas sûr que l'on respecte la documentation. Quel est l’inconvénient pour toi de ne pas avoir l'EnteteRequeteType dans le header soap?

[aminvielledebat]

Aucun inconvénient de mon côté. C'est simplement une interprétation de la spécification que j ai pu faire.
Je suis parti du principe que si l'objet s'appelait "entête", il y avait des chances que cela soit un entête :-)

Après, en y réfléchissant, je ne trouve pas absurde que ces informations là ne soient pas dans le body (on parle de paramètres techniques ou d'éléments permettant la validation de la signature du contrat, pas d'informations liées à la mutation à proprement parlé).

Pour moi, c'est le genre de sujets sur lequel les représentants techniques peuvent proposer une solution répondant au besoin de la spec. On reste conforme selon moi. Aux representants de trancher (via une autre PR)

[aminvielledebat]

@jlsaxione un avis là dessus ? On fait une PR à côté pour sortir l'objet d'entête du body, et le mettre dans le header soap ou on reste en l'état ?

[aminvielledebat]

tracé dans la #22

[aminvielledebat]

@jlsaxione @dlevasseuraltitude, je propose que l'on valide les derniers échanges que l'on a pu avoir (le fichier que je t'ai envoyé, si cela te convient @dlevasseuraltitude) et que l'on fasse d'autres PRs pour la suite, sinon cela vite devenir illisible.

De mon côté, j'en prépare une autre pour la mise en conformité avec la spec (il manque encore pas mal de restrictions).

En phase avec ça ?

[jlsaxione]

en phase avec ça même si je vous ai laissé travailler sur le sujet tous les deux.
Il faudra aussi diffuser ce wsdl, voir le tagger pour que les MOA le propage vers toutes les équipes de dev de chaque opérateur.

[aminvielledebat]

Ping pour cette PR @dlevasseuraltitude (Ok pour Jérôme), comme ça, vous pourrez jeter un coup d'oeil à la #21 où j'ai repris les restrictions et l'ordre des champs dans les séquences, comme défini dans la spec interop'.

[jlsaxione]

on accepte le merge ?

[aminvielledebat]

Yes. Il faut que l'on avance, et il reste pas mal de non conformités que j'ai corrigé dans ma dernière #21.

Reste à corriger ce qui fait péter le build travis.