🛅 🌧️ 👍 XSD प्रतिबंधों के समर्थन के साथ JAX-WS का स्व-दस्तावेजीकरण 🦊 👩🏿‍🤝‍👨🏾 😎

इस लेख में, मैं एक स्व-दस्तावेजीकरण वेब सेवा (jax-ws) बनाने के बारे में बात करूंगा जो XSD प्रतिबंध तत्वों का उपयोग करता है।

कार्य विवरण

"प्रोग्रामर प्रैग्मेटिस्ट" पुस्तक में प्रलेखन पर एक अध्याय है। यह कहता है कि सूचना का एक स्रोत होना चाहिए, और इसके आधार पर, इस जानकारी के व्युत्पन्न रूप उत्पन्न होते हैं। उदाहरण के लिए, तालिकाओं की संरचना के बारे में सभी जानकारी एक प्रारूप में संग्रहीत की जाती है (यह किसी भी उपयुक्त या मालिकाना प्रारूप की एक फ़ाइल हो सकती है), और इसके आधार पर तालिकाएँ स्वयं उत्पन्न होती हैं, इन तालिकाओं के लिए प्रलेखन, तालिकाओं के साथ काम करने के लिए डीएओ ऑब्जेक्ट। इस दृष्टिकोण के फायदे यह हैं कि प्रस्तुत जानकारी के व्युत्पन्न रूपों के बीच कोई वंशानुक्रम नहीं होगा, क्योंकि जिस स्थान पर जानकारी संपादित की जाएगी, वह एकमात्र मूल स्रोत है।

नकारात्मक पक्ष यह है कि सभी इच्छुक लोगों को इस फाइल को संपादित करने में सक्षम होना चाहिए और वांछित प्रारूपों के लिए कन्वर्टर्स होना चाहिए।

वेब सेवाओं में, इन अवधारणाओं को पहले अनुबंध और अंतिम अनुबंध कहा जाता है। पहला अनुबंध - जब wsdl पहली बार बनाया जाता है, और जावा कोड इससे उत्पन्न होता है। अनुबंध अंतिम - इसके विपरीत, पहले जावा कोड, और उसके अनुसार wsdl।

आप पेशेवरों और विपक्ष के बारे में लिंक पर पढ़ सकते हैं: docs.spring.io/spring-ws/sites/1.5/reference/html/why-contract-first.html stackoverflow.com/questions/76h27/which-is-the-better- दृष्टिकोण करने के लिए वेब सेवाओं के अनुबंध-पहले या अनुबंध-पिछले

इस अनुच्छेद में, मैं एक समान समाधान प्राप्त करने के लिए स्व-प्रलेखन के साथ एक SOAP वेब सेवा बनाने पर विचार करूंगा - वेब सेवाओं के बारे में सभी जानकारी इसमें निहित होगी। यह पता चला है कि यह एक प्रकार का "अनुबंध अंतिम" है - पहले कोड लिखा जाता है, और फिर wsdl के रूप में प्रलेखन प्राप्त किया जाता है जिसमें इस वेब सेवा के बारे में अधिकतम जानकारी होती है - उन सभी विधियों और प्रकारों पर टिप्पणी, जिनके साथ सेवा काम करती है और डेटा शुद्धता के लिए जाँच के अधिकांश तर्क। यह समाधान क्यों उपयोगी हो सकता है? मामले में जब सभी विकास लेखन कोड पर केंद्रित होते हैं और इसके आधार पर wsdl उत्पन्न होता है, न कि इसके विपरीत। या जब शुरू में wsdl में प्रलेखन बनाए रखना मुश्किल हो। लेकिन अगर वेब तरीकों को एनालिटिक्स के लिए लिखा जाता है, तो इस एनालिटिक्स को wsdl में स्टोर करना बेहतर है। यानी wsdl पहले, और विधियाँ, कक्षाएं, और पठनीय प्रलेखन इससे उत्पन्न होते हैं। अन्यथा, उन लोगों के साथ पहले से लिखी गई सेवा के अनुपालन की जांच करने में समस्याएं होंगी। कार्य।

Xsd की ओर से वैधता के लिए इनपुट डेटा की जांच करना भी बेहतर है, ताकि आप वेब सेवा से कनेक्ट किए बिना अनुरोध की जांच कर सकें और यह तर्क दिखाई दे रहा है (xsd में), और सेवा के आंत्रों में कहीं वायर्ड नहीं है।

समाधान के विकल्प

वर्तमान में, आप किसी भी jax-ws एप्लिकेशन से wsdl प्राप्त कर सकते हैं। लेकिन मानक jax-ws / jaxb एनोटेशन वेब सेवाओं के लिए प्रलेखन का समर्थन नहीं करते हैं - इसके लिए आपको तीसरे पक्ष के ढांचे द्वारा प्रदान की गई क्षमताओं का उपयोग करने की आवश्यकता है। विशेष रूप से, अपाचे CXF (jax-ws) WSDLDocumentation एनोटेशन प्रदान करता है, जो वेब विधियों पर लागू होता है और जो वेब विधि का वर्णन करता है, जो बाद में wsdl में समाप्त हो जाएगा। Jaxb - facets लाइब्रेरी ( dsg.tuwien.ac.at/staff/hummer/tools/jaxb-facets.html , github.com/whummer/jaxb-facets ) का उपयोग xml संस्थाओं को दस्तावेज करने के लिए किया जाता है जिनका उपयोग वेब विधियों में किया जाएगा। यह वेब तरीकों के लिए CXF की तरह अनुमति देता है, वर्गों और xml सेम के क्षेत्रों दस्तावेज़ करने के लिए। इसके अलावा, यह एक्सएसडी प्रतिबंधों के लिए समर्थन जोड़ता है - एक्सएमएल क्षेत्रों के मूल्यों पर अतिरिक्त प्रतिबंध। ( एक्सएसडी प्रतिबंधों का वर्णन यहाँ है www.w3schools.com/schema/schema_facets.asp ) यह तब उपयोगी होगा जब आपको अनिवार्य / वैकल्पिक से अधिक जटिल मूल्यों की शुद्धता की जाँच के तर्क की आवश्यकता होगी - क्योंकि jaxb पूरी तरह से xsd की सत्यापन क्षमताओं का समर्थन नहीं करता है। विशेष रूप से, न्यूनतम, अधिकतम मूल्यों पर प्रतिबंध निर्दिष्ट करना, नियमित अभिव्यक्ति का उपयोग करना, रिक्त मानों पर प्रसंस्करण स्ट्रिंग के विभिन्न तरीकों का उपयोग करना, मूल्य की लंबाई पर सीमा निर्धारित करना संभव होगा।

कार्यान्वयन

एक उदाहरण के रूप में, आइए कई तरीकों से एक सरल वेब सेवा बनाएं।

लेख में मैं कोड के टुकड़ों के साथ विशिष्ट उदाहरणों का वर्णन करूंगा। पूरी सेवा dl.dropboxusercontent.com/u/7519092/jax-ws-example.zip पर डाउनलोड की जा सकती है। यह एक आईडिया मावेन परियोजना है। IDEA में, आप IDEA प्रोजेक्ट आयात करके या मावेन प्रोजेक्ट आयात करके या तो खोल सकते हैं। Pom.xml को xslt का उपयोग करके html में इसके रूपांतरण के साथ एक wsdl फ़ाइल उत्पन्न करने के लिए कॉन्फ़िगर किया गया है, लेकिन दुर्भाग्य से इस wsdl में jaxb-facets से प्रलेखन टैग नहीं है, हालांकि यह wsdl (लिंक पथ के माध्यम से सुलभ) / web_service / WebService द्वारा उत्पन्न होता है? wsdl) यह टैग है। इसके अलावा परियोजना में, एनोटेशन के उपयोग में भिन्नता है - वहाँ एनोटेशन तरीकों को प्राप्त करने के लिए लागू होते हैं, और इन उदाहरणों में कक्षा के क्षेत्रों के लिए। यह लेख को छोटा करने के लिए किया जाता है। किसी वर्ग के फ़ील्ड में एनोटेशन लागू करने के लिए, आपको या तो तरीके नहीं लाने चाहिए या @XmlAccessorType (XmlAccessType.FIELD) निर्दिष्ट करना होगा।

उदाहरण

उदाहरण के रूप में, कई विशिष्ट कार्यों पर विचार करें

दिनांक और समय के अधिकतम और न्यूनतम मूल्यों पर प्रतिबंध।

दिनांक के लिए:

@XmlSchemaType(name = "date") @Facets(minInclusive = "1900-01-01", maxInclusive = "9999-12-31Z") Date date;

जेनरेट किया गया xsd सर्किट:

 <xs:element minOccurs="0" name="date"> <xs:simpleType> <xs:restriction base="xs:date"> <xs:maxInclusive value="9999-12-31Z"/> <xs:minInclusive value="1900-01-01"/> </xs:restriction> </xs:simpleType> </xs:element>

 @XmlSchemaType(name = "dateTime") @Facets(minInclusive = "1900-01-01T00:00:00", maxInclusive = "9999-12-31T23:59:59") Date dateTime;

 <xs:element minOccurs="0" name="dateTime"> <xs:simpleType> <xs:restriction base="xs:dateTime"> <xs:maxInclusive value="9999-12-31T23:59:59"/> <xs:minInclusive value="1900-01-01T00:00:00"/> </xs:restriction> </xs:simpleType> </xs:element>

(जक्सबेट-लाइब्रेरी से पहलुओं द्वारा सार)

हमें इस्तेमाल करना पड़ा क्योंकि डीबीएमएस ने जावा में उपलब्ध तारीख सीमा का समर्थन नहीं किया। यानी वेब सेवा में, आप तारीखों को स्थानांतरित कर सकते हैं, उदाहरण के लिए, 1000-01-01 और जावा में यह सही ढंग से पार्स करेगा, लेकिन DBMS को लिखते समय एक त्रुटि होगी, क्योंकि यह इस तिथि सीमा का समर्थन नहीं करता है। और स्वीकृत मूल्यों को सीमित करने के लिए, यह प्रतिबंध पेश किया गया है।

एक तिथि के लिए, अधिकतम तिथि को समय क्षेत्र को ध्यान में रखते हुए दिया जाता है। यह आवश्यक है कि समय क्षेत्र के साथ आउटपुट 9999-12-31 का समर्थन करता है (उदाहरण के लिए, 9999-12-31 + 04: 00)। यदि ऐसा नहीं किया जाता है, तो इस मान को क्रमबद्ध करते समय (क्लाइंट को लौटते समय) एक xsd सत्यापन त्रुटि होगी।

एक विशिष्ट फ़ील्ड लंबाई पर सीमा

 @Facets(length = 16) String id;

 <xs:element minOccurs="0" name="id"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:length value="16"/> </xs:restriction> </xs:simpleType> </xs:element>

यह आवश्यक है, उदाहरण के लिए, जब क्षेत्र एक निश्चित लंबाई या विशिष्ट लंबाई के कुछ अन्य पहचानकर्ता का एक विशिष्ट पहचानकर्ता है - पासपोर्ट की संख्या, कार्ड।

हालांकि आईडी के मामले में, आप एक अलग प्रकार के आईडी को अलग कर सकते हैं:

 public class Id { @Facets(length = 16) @XmlAttribute String attr; }

और इसे इस तरह से उपयोग करें:

 Id id;

तो हम स्पष्ट रूप से संकेत देंगे कि यह एक चर है - एक अद्वितीय पहचानकर्ता, जबकि सभी प्रतिबंध काम करेंगे।

रिसेटिंग फील्ड्स

कुछ वैकल्पिक फ़ील्ड को साफ़ करने की आवश्यकता है। स्ट्रिंग्स के लिए, यह बहुत सरलता से किया जाता है - एक खाली टैग भेजा जाता है (उदाहरण <नाम />) और जब अनमर्सहॉलिंग (जावा वस्तुओं के लिए एक xml अनुरोध को परिवर्तित करना) हमें बस एक खाली स्ट्रिंग मिलती है (String.isEmpty (TM == true)। और इसे पूरी तरह से एक स्ट्रिंग के रूप में व्याख्या किया जा सकता है जिसे शून्य करने की आवश्यकता है।

लेकिन अगर आपको संख्या या दिनांक रीसेट करने की आवश्यकता है, तो खाली टैग पास करते समय एक त्रुटि होगी:

अनमर्शिंग त्रुटि: cvc-datatype-valid.1.2.1.1: '' 'पूर्णांक' के लिए मान्य मान नहीं है

यह समझ में आता है - एक खाली टैग को एक संख्या के रूप में नहीं दिखाया जा सकता है (शून्य माना नहीं जाता है - अशक्त एक टैग की अनुपस्थिति है)।

यह फ़ील्ड के लिए डिफ़ॉल्ट मान का उपयोग करके हल किया जा सकता है।

 @XmlElement(defaultValue = "-2147483648") Integer id;

 <xs:element default="-2147483648" minOccurs="0" name="id" type="xs:int"/>

इसके अलावा, यदि आप जावा में एक खाली टैग (<id />) पास करते हैं, तो आईडी वैरिएबल -2147483648 (यह Integer.MIN_VALUE है) मान लेगा। यह समाधान एक नल ऑब्जेक्ट पैटर्न की तरह एक सा है - जब आपको यह इंगित करने की आवश्यकता होती है कि एक शून्य मान स्पष्ट रूप से पारित हो गया है (और बस एक मूल्य निर्दिष्ट नहीं किया गया है), तो हम एक विशेष अशक्त वस्तु को पास करते हैं।

en.wikipedia.org/wiki/Null_Object_pattern

तारीखों के लिए, एक ही दृष्टिकोण इस तरह दिखेगा:

 @XmlSchemaType(name = "date") @XmlElement(defaultValue = "1900-01-01") Date date;

 <xs:element default="1900-01-01" minOccurs="0" name="date" type="xs:date"/>

 @XmlSchemaType(name = "dateTime") @XmlElement(defaultValue = "1900-01-01T00:00:00") Date dateTime;

 <xs:element default="1900-01-01T00:00:00" minOccurs="0" name="dateTime" type="xs:dateTime"/>

कुछ दस्तावेज़ीकृत

फील्ड डॉक्यूमेंटेशन डॉक्यूमेंटेशन एनोटेशन (jaxb-facets लाइब्रेरी से) का उपयोग करके किया जाता है।

 @XmlSchemaType(name = "date") @Documentation("  ") @Facets(minInclusive = "1900-01-01", maxInclusive = "9999-12-31Z") Date date;

 <xs:element minOccurs="0" name="date"> <xs:annotation> <xs:documentation>  </xs:documentation> </xs:annotation> <xs:simpleType> <xs:restriction base="xs:date"> <xs:maxInclusive value="9999-12-31Z"/> <xs:minInclusive value="1900-01-01"/> </xs:restriction> </xs:simpleType> </xs:element>

सीएक्सएफ से डब्ल्यूएसडीएलडीएनजेडेशन एनोटेशन का उपयोग करके वेब सेवा विधियों का दस्तावेजीकरण किया जाता है।

 @WSDLDocumentation("   .     XML Schema Restrictions") String facetsExampleMethod(FacetsExample request);

 <wsdl:operation name="facetsExampleMethod"> <wsdl:documentation>    .     XML Schema Restrictions </wsdl:documentation> <wsdl:input message="tns:facetsExampleMethod" name="facetsExampleMethod"/> <wsdl:output message="tns:facetsExampleMethodResponse" name="facetsExampleMethodResponse"/> </wsdl:operation>

इन क्षेत्रों और विधियों का आगे वर्णन wsdl में पाया जा सकता है।

सेवा प्रलेखन पीढ़ी (wsdl से html)

जेनरेट किए गए wsdl को पढ़ने योग्य दृश्य में बदलने के लिए, xslt फ़ाइल tomi.vanek.sk/index.php?page=wsdl-viewer SoapUI का उपयोग करके पठनीय HTML भी बना सकते हैं। यह सब StackOverflow पर वर्णित है:

stackoverflow.com/questions/686103/generating-html-documentation-from-wsdl HTML को बिल्ड स्टेज पर रूपांतरण pom.xml में कार्यान्वित किया जाता है। अगला यह पृष्ठ <एप्लीकेशन पथ> /WWService.html पर उपलब्ध होगा।

कुछ HTML पीढ़ी के नोट नहीं:

वेब विधियों के मापदंडों को सही ढंग से केवल तभी प्रदर्शित किया जाता है यदि @SOAPBinding (शैली = SOAPBinding.Style.RPC) निर्दिष्ट किया गया हो।

डॉक्यूमेंटेशन एनोटेशन wsdl में हो जाता है और, तदनुसार, HTML डॉक्युमेंटेशन में केवल जब रनटाइम रनिंग सर्विस से wsdl जेनरेट कर रहा होता है। जब wsdl का निर्माण किया जाता है तो उसमें दस्तावेज नहीं होते हैं ऐसा क्यों - मुझे नहीं पता। सबसे अधिक संभावना wsdl जनरेटर त्रुटि।

जक्सब-पहलुओं की अन्य विशेषताएं

मैं संक्षेप में jaxb-facets की अन्य विशेषताओं के बारे में बात करूँगा जिनका मैंने उपयोग किया था:

एक नियमित अभिव्यक्ति द्वारा एक मूल्य की जाँच - Facets.pattern।

व्हॉट्सएप प्रोसेसिंग लॉजिक सेट करना - Facets.whiteSpace। व्हाट्सएप को खाते में रखा जा सकता है, हटा दिया गया है, रिक्त स्थान (टैब और लाइन ब्रेक के लिए) के साथ बदल दिया गया है। केवल तब काम करता है जब xsd में जाँच की जाती है, अर्थात व्हॉट्सएप के पात्रों के साथ जावा कोड को वैसा ही मूल्य मिलता है। यह सत्यापित करना उपयोगी होगा कि स्ट्रिंग फ़ील्ड अनिवार्य है, जब रिक्त स्थान से भरा फ़ील्ड को खाली के रूप में भी व्याख्या किया जाना चाहिए।

सामान्य तौर पर, jaxb-facets सभी xsd प्रतिबंध का समर्थन करता है। आप पृष्ठ के अंत में www.w3schools.com/schema/schema_facets.asp पृष्ठ के अंत में उनके साथ खुद को परिचित कर सकते हैं। इसके अलावा नवीनतम संस्करण (2.2.6) xs में: मुखर समर्थन दिखाई दिया। उदाहरण xs: IBM वेबसाइट ( www.ibm.com/developerworks/en/library/x-xml1152 ) से मुखर करें:

 <xs:element name="dimension"> <xs:complexType> <xs:attribute name="height" type="xs:int"/> <xs:attribute name="width" type="xs:int"/> <xs:assert test="@height < @width"/> </xs:complexType> </xs:element>

टिप्पणी

मैं दोहराता हूं, सामान्य तौर पर, यदि कोई सेवा "स्क्रैच" से लिखी जाती है, तो सही wsdl बनाना बेहतर होता है, और पहले से ही जावा कोड और डॉक्यूमेंटेशन तैयार किया जाता है। लेकिन अगर आपके पास पहले से ही एक लिखित वेब सेवा है, तो इसमें XSD प्रतिबंधों को जोड़ने से ग्राहक की ओर से इसे और अधिक पारदर्शी बना दिया जाएगा - वह इनपुट मानों की जांच करने का तर्क देखेंगे (हालांकि, निश्चित रूप से, सभी नहीं - कुछ मामलों में DBMS तक पहुंच के बिना प्रश्नों की शुद्धता की जांच करना असंभव है। कुछ संबंधित संसाधन)। इसके अलावा, प्रलेखन पीढ़ी आपको अपने मापदंडों, तकनीक के साथ वास्तविक वेब विधियों के पत्राचार की आसानी से तुलना करने की अनुमति देगा। निर्देश। इसके बिना, किसी को भी टाइप करके जांच करनी होगी - वेब विधियों के अनुरोधों और उत्तरों को देखना, या उत्पन्न wsdl की पेचीदगियों को समझना।

XSD प्रतिबंधों के समर्थन के साथ JAX-WS का स्व-दस्तावेजीकरण