Java क्लाइंट लाइब्रेरी का इस्तेमाल करना

इस दस्तावेज़ में, Google Data API ("GData") क्वेरी भेजने और मिले हुए जवाबों को समझने के लिए, Java क्लाइंट लाइब्रेरी का इस्तेमाल करने का तरीका बताया गया है.

Google, डेटा एपीआई वाली सेवाओं के साथ इंटरैक्ट करने के लिए, कई प्रोग्रामिंग भाषाओं में क्लाइंट लाइब्रेरी का एक सेट उपलब्ध कराता है. इन लाइब्रेरी का इस्तेमाल करके, GData अनुरोध बनाए जा सकते हैं. साथ ही, उन्हें किसी सेवा पर भेजा जा सकता है और जवाब पाए जा सकते हैं.

इस दस्तावेज़ में, Java क्लाइंट लाइब्रेरी का इस्तेमाल करने के बारे में सामान्य जानकारी दी गई है. साथ ही, इसके सामान्य इस्तेमाल के कुछ उदाहरण भी दिए गए हैं.

इस क्लाइंट लाइब्रेरी का इस्तेमाल करने के लिए, आपके पास Java 1.5 होना चाहिए.

Java क्लाइंट लाइब्रेरी डाउनलोड करें.

इस गाइड में दिए गए उदाहरण, Google Calendar API के बारे में बताते हैं. हालांकि, यह गाइड Calendar API के इस्तेमाल के बारे में सटीक या अप-टू-डेट जानकारी नहीं देती है. किसी सेवा के डेटा एपीआई के साथ Java क्लाइंट लाइब्रेरी का इस्तेमाल करने के बारे में जानकारी पाने के लिए, सेवा से जुड़ा दस्तावेज़ देखें. उदाहरण के लिए, अगर आपको Calendar के साथ काम करना है, तो Calendar Data API डेवलपर गाइड पढ़ें.

सामग्री

ऑडियंस

यह दस्तावेज़, Java प्रोग्रामर के लिए है. इसमें क्लाइंट ऐप्लिकेशन लिखने के बारे में बताया गया है, ताकि वे GData सेवाओं के साथ इंटरैक्ट कर सकें.

इस दस्तावेज़ में यह मान लिया गया है कि आपको Google Data APIs प्रोटोकॉल के बारे में सामान्य जानकारी है. हम यह भी मानकर चलते हैं कि आपको Java में प्रोग्रामिंग करना आता है.

क्लाइंट लाइब्रेरी की ओर से उपलब्ध कराई गई क्लास और तरीकों के बारे में रेफ़रंस जानकारी के लिए, Java क्लाइंट लाइब्रेरी का एपीआई रेफ़रंस (Javadoc फ़ॉर्मैट में) देखें.

इस दस्तावेज़ को क्रम से पढ़ने के लिए डिज़ाइन किया गया है. हर उदाहरण, पिछले उदाहरणों पर आधारित है.

डेटा मॉडल की खास जानकारी

Java क्लाइंट लाइब्रेरी, Google Data API के इस्तेमाल किए गए एलिमेंट को दिखाने के लिए क्लास के सेट का इस्तेमाल करती है. उदाहरण के लिए, एक Feed क्लास है, जो <atom:feed> एलिमेंट से मेल खाती है. इसमें एंट्री बनाने, अलग-अलग सब-एलिमेंट की वैल्यू पाने और सेट करने के तरीके शामिल हैं. इसमें एक एंट्री क्लास भी होती है, जो <atom:entry> एलिमेंट से मेल खाती है. Google Data API में तय किए गए हर एलिमेंट की अपनी क्लास नहीं होती. ज़्यादा जानकारी के लिए, रेफ़रंस दस्तावेज़ देखें.

यह लाइब्रेरी, Atom कॉन्टेंट को अपने-आप पार्स कर सकती है. साथ ही, Atom एलिमेंट की वैल्यू को सही ऑब्जेक्ट में डाल सकती है. उदाहरण के लिए, getFeed तरीके से फ़ीड मिलता है, उसे पार्स किया जाता है, और नतीजे के तौर पर मिली वैल्यू के साथ Feed ऑब्जेक्ट मिलता है.

किसी सेवा को फ़ीड या एंट्री भेजने के लिए, फ़ीड या एंट्री ऑब्जेक्ट बनाया जाता है. इसके बाद, ऑब्जेक्ट को एक्सएमएल में अपने-आप बदलने और उसे भेजने के लिए, लाइब्रेरी के किसी तरीके (जैसे कि insert तरीका) को कॉल किया जाता है.

अगर आपको पसंद है, तो XML को पार्स और/या जनरेट किया जा सकता है. ऐसा करने का सबसे आसान तरीका, Rome जैसी तीसरे पक्ष की लाइब्रेरी का इस्तेमाल करना है.

Google Data API के एक्सएमएल सिंटैक्स की तरह ही, इससे जुड़ा ऑब्जेक्ट मॉडल भी बढ़ाया जा सकता है. उदाहरण के लिए, क्लाइंट लाइब्रेरी, Google Data नेमस्पेस में तय किए गए एलिमेंट के हिसाब से क्लास उपलब्ध कराती है.

ट्यूटोरियल और उदाहरण

यहां दिए गए उदाहरणों में, Java क्लाइंट लाइब्रेरी का इस्तेमाल करके, अलग-अलग डेटा एपीआई अनुरोध भेजने का तरीका बताया गया है.

इन उदाहरणों को ज़्यादा सटीक बनाने के लिए, इनमें यह दिखाया गया है कि किसी सेवा, जैसे कि Google Calendar के साथ कैसे इंटरैक्ट किया जाता है. हम उन जगहों के बारे में बताएंगे जहां Calendar, Google की अन्य सेवाओं से अलग है. इससे आपको इन उदाहरणों को अन्य सेवाओं के साथ इस्तेमाल करने में मदद मिलेगी. Calendar के बारे में ज़्यादा जानने के लिए, Google Calendar Data API से जुड़ा दस्तावेज़ देखें.

क्लाइंट बनाना और उसे चलाना

इस दस्तावेज़ में दिए गए उदाहरणों को कंपाइल करने के लिए, आपको इन इंपोर्ट स्टेटमेंट का इस्तेमाल करना होगा:

import com.google.gdata.client.*;
import com.google.gdata.client.calendar.*;
import com.google.gdata.data.*;
import com.google.gdata.data.extensions.*;
import com.google.gdata.util.*;
import java.net.URL;

फ़ीड का अनुरोध करना

Google Calendar Data API दस्तावेज़ में बताए गए तरीके से, Calendar फ़ीड का अनुरोध किया जा सकता है. इसके लिए, Calendar को यह एचटीटीपी अनुरोध भेजें:

GET http://www.google.com/calendar/feeds/userID/private/full

आपको userID की जगह उपयोगकर्ता का ईमेल पता डालना होगा. ज़्यादा जानकारी के लिए, Calendar का दस्तावेज़ देखें. इसके बजाय, Calendar के साथ इंटरैक्ट करने के लिए, खास डिफ़ॉल्ट यूआरएल का इस्तेमाल किया जा सकता है. इसके बारे में Calendar के दस्तावेज़ में बताया गया है. हालांकि, इस दस्तावेज़ में हम निजी फ़ुल फ़ीड यूआरएल का इस्तेमाल करेंगे, जिसमें उपयोगकर्ता आईडी शामिल होता है.

आपको पुष्टि करने का सही तरीका भी अपनाना होगा. इस उदाहरण और Calendar दस्तावेज़ में दिए गए पहले उदाहरण के बीच मुख्य अंतर यह है कि (1) इस उदाहरण में पुष्टि करने की सुविधा शामिल है और (2) यह उदाहरण, Calendar से जुड़ी CalendarService क्लास के बजाय, ज़्यादा सामान्य GoogleService क्लास का इस्तेमाल करता है.

ध्यान दें कि यहां इस्तेमाल किया जा रहा पुष्टि करने वाला सिस्टम ("इंस्टॉल किए गए ऐप्लिकेशन के लिए Google की पुष्टि करने की सुविधा" के नाम से जाना जाता है) सिर्फ़ इंस्टॉल किए गए क्लाइंट ऐप्लिकेशन, जैसे कि डेस्कटॉप क्लाइंट में इस्तेमाल किया जा सकता है. इसे वेब ऐप्लिकेशन में इस्तेमाल नहीं किया जा सकता. प्रमाणीकरण के बारे में ज़्यादा जानकारी के लिए, Google खाते के प्रमाणीकरण से जुड़ा दस्तावेज़ देखें.

Java क्लाइंट लाइब्रेरी का इस्तेमाल करके, "liz@gmail.com" ईमेल पते और "mypassword" पासवर्ड वाले उपयोगकर्ता के लिए, Calendar फ़ीड का अनुरोध करने के लिए, इस कोड का इस्तेमाल करें:

// Set up the URL and the object that will handle the connection:
URL feedUrl = new URL("http://www.google.com/calendar/feeds/liz@gmail.com/private/full");
GoogleService myService = new GoogleService("cl", "exampleCo-exampleApp-1");
myService.setUserCredentials("liz@gmail.com", "mypassword");

// Mark the feed as an Event feed:
new EventFeed().declareExtensions(myService.getExtensionProfile());

// Send the request and receive the response:
Feed myFeed = myService.getFeed(feedUrl, Feed.class);

GoogleService क्लास, GData सेवा से क्लाइंट कनेक्शन (पुष्टि के साथ) को दिखाता है. क्लाइंट लाइब्रेरी का इस्तेमाल करके, किसी सेवा को क्वेरी भेजने की सामान्य प्रक्रिया में ये चरण शामिल होते हैं:

  1. सही यूआरएल पाएं या बनाएं.
  2. अगर आपको किसी सेवा को डेटा भेजना है (उदाहरण के लिए, अगर आपको नई एंट्री डालनी है), तो क्लाइंट लाइब्रेरी क्लास का इस्तेमाल करके, रॉ डेटा को ऑब्जेक्ट में बदलें. (अगर आपको सिर्फ़ फ़ीड का अनुरोध करना है, तो यह चरण लागू नहीं होता. जैसा कि इस उदाहरण में किया गया है.)
  3. एक नया GoogleService इंस्टेंस बनाएं. इसमें सेवा का नाम (जैसे, Calendar के लिए "cl") और आपके ऐप्लिकेशन का नाम (companyName-applicationName-versionID के तौर पर) सेट करें.
  4. सही क्रेडेंशियल सेट करें.
  5. क्लाइंट लाइब्रेरी को बताएं कि फ़ीड किन एक्सटेंशन का इस्तेमाल करेगा, ताकि लाइब्रेरी, दिखाए गए फ़ीड को सही तरीके से पार्स कर सके.
  6. अनुरोध भेजने और नतीजे पाने के लिए, किसी तरीके को कॉल करें.

setUserCredentials तरीके से, उस उपयोगकर्ता का आईडी और पासवर्ड तय किया जाता है जिसकी ओर से आपका क्लाइंट क्वेरी भेज रहा है. इस दस्तावेज़ में दिए गए उदाहरणों में, "इंस्टॉल किए गए ऐप्लिकेशन के लिए पुष्टि करने की सुविधा" का इस्तेमाल किया गया है. पुष्टि करने की सुविधाओं के बारे में ज़्यादा जानने के लिए, Google खाते की पुष्टि करने की सुविधा से जुड़ा दस्तावेज़ देखें.

क्रेडेंशियल सेट करने के बाद, declareExtensions तरीके को कॉल करके यह बताया जाता है कि फ़ीड किन एक्सटेंशन का इस्तेमाल करेगा. इस मामले में, हम यह बता रहे हैं कि फ़ीड एक इवेंट फ़ीड है. इसलिए, यह इवेंट टाइप के हिसाब से तय किए गए एक्सटेंशन का इस्तेमाल करेगा.

पूरे फ़ीड का अनुरोध करने के लिए, getFeed तरीके का इस्तेमाल करें. यह तरीका, यूआरएल लेता है और उस यूआरएल पर मौजूद पूरा फ़ीड दिखाता है. हम इस दस्तावेज़ में आगे बताएंगे कि ज़्यादा सटीक क्वेरी कैसे भेजी जाती हैं.

GoogleService क्लास के अन्य तरीकों की तरह, getFeed भी पुष्टि करने और रीडायरेक्ट करने की प्रोसेस को ज़रूरत के मुताबिक मैनेज करता है.

नया आइटम डालना

नया कैलेंडर इवेंट बनाने के लिए, इस कोड का इस्तेमाल किया जा सकता है:

URL postUrl =
  new URL("http://www.google.com/calendar/feeds/liz@gmail.com/private/full");
EventEntry myEntry = new EventEntry();

myEntry.setTitle(new PlainTextConstruct("Tennis with Darcy"));
myEntry.setContent(new PlainTextConstruct("Meet for a quick lesson."));

Person author = new Person("Elizabeth Bennet", null, "liz@gmail.com");
myEntry.getAuthors().add(author);

DateTime startTime = DateTime.parseDateTime("2006-04-17T15:00:00-08:00");
DateTime endTime = DateTime.parseDateTime("2006-04-17T17:00:00-08:00");
When eventTimes = new When();
eventTimes.setStartTime(startTime);
eventTimes.setEndTime(endTime);
myEntry.addTime(eventTimes);

// Send the request and receive the response:
EventEntry insertedEntry = myService.insert(postUrl, myEntry);

यूआरएल सेट करने के बाद, हम एक EventEntry ऑब्जेक्ट बनाते हैं; EventEntry, ऐब्स्ट्रैक्ट बेस क्लास BaseEntry से लिया गया है. यह Entry क्लास के लिए पैरंट क्लास भी है. यह <atom:entry> एलिमेंट को दिखाता है.

EventEntry क्लास, इवेंट टाइप को दिखाता है. ज़्यादा जानकारी के लिए, टाइप का दस्तावेज़ देखें. Calendar के अलावा अन्य सेवाओं के लिए, हो सकता है कि आपको EventEntry ऑब्जेक्ट के बजाय, Entry ऑब्जेक्ट को वापस की गई एंट्री असाइन करनी पड़े.

एंट्री का टाइटल एक TextConstruct है. यह एक ऐसी क्लास है जिसमें टेक्स्ट को अलग-अलग फ़ॉर्मैट (सादा टेक्स्ट, एचटीएमएल या एक्सएचटीएमएल) में रखा जाता है. एंट्री के कॉन्टेंट को Content ऑब्जेक्ट के तौर पर दिखाया जाता है. यह एक ऐसी क्लास है जिसमें सादा टेक्स्ट या अन्य तरह का कॉन्टेंट शामिल हो सकता है. इसमें एक्सएमएल और बाइनरी डेटा भी शामिल है. (हालांकि, setContent वाला तरीका, TextConstruct को भी स्वीकार कर सकता है.)

हर लेखक को नाम, यूआरआई, और ईमेल पते के तौर पर दिखाया जाता है. (इस उदाहरण में, हम यूआरआई को शामिल नहीं कर रहे हैं.) किसी एंट्री में लेखक को जोड़ने के लिए, एंट्री के getAuthors().add तरीके को कॉल करें.

हम उसी GoogleService ऑब्जेक्ट का इस्तेमाल कर रहे हैं जिसे हमने पिछले उदाहरण में बनाया था. इस मामले में, कॉल करने का तरीका insert है. यह आइटम को बताए गए इंसर्शन यूआरएल पर भेजता है.

यह सेवा, नई बनाई गई एंट्री दिखाती है. इसमें सर्वर से जनरेट किए गए अन्य एलिमेंट भी शामिल हो सकते हैं. जैसे, एंट्री के लिए बदलाव करने का यूआरएल.

एचटीटीपी स्टेटस कोड, अपवाद के तौर पर दिखाए जाते हैं.

ऊपर दिया गया कोड, POST http://www.google.com/calendar/feeds/liz@gmail.com/private/full (सही पुष्टि के साथ) भेजने और इवेंट के तौर पर एंट्री देने के बराबर है.

किसी खास एंट्री का अनुरोध करना

नीचे दिए गए कोड की मदद से, उस खास एंट्री का अनुरोध किया जा सकता है जिसे आपने पिछले उदाहरण में डाला था.

उदाहरणों की इस सीरीज़ के हिसाब से, उस एंट्री को वापस पाना ज़रूरी नहीं है, क्योंकि Calendar ने पहले ही डाली गई एंट्री वापस कर दी है. हालांकि, जब भी आपको किसी एंट्री का यूआरआई पता हो, तब इस तकनीक का इस्तेमाल किया जा सकता है.

URL entryUrl = new URL(insertedEntry.getSelfLink().getHref());
EventEntry retrievedEntry = myService.getEntry(entryUrl, EventEntry.class);

डालने के लिए चुनी गई एंट्री में एक तरीका, getSelfLink होता है. यह Link ऑब्जेक्ट दिखाता है. इसमें एंट्री का यूआरएल शामिल होता है. Link क्लास में एक getHref तरीका होता है, जो यूआरएल को String के तौर पर दिखाता है. इससे हम यूआरएल ऑब्जेक्ट बना सकते हैं.

इसके बाद, हमें एंट्री पाने के लिए, सेवा के getEntry तरीके को कॉल करना होगा.

ध्यान दें कि हम EventEntry.class को getEntry के पैरामीटर के तौर पर देते हैं. इससे पता चलता है कि हम खास तौर पर सेवा से, सिर्फ़ एक सामान्य एंट्री के बजाय एक इवेंट वापस पाने की उम्मीद कर रहे हैं. Calendar के अलावा अन्य सेवाओं के लिए, सिर्फ़ Entry.class पास किया जा सकता है.

ऊपर दिया गया कोड, Calendar को GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID भेजने के बराबर है. हालांकि, इसके लिए पुष्टि करना ज़रूरी है.

एंट्री खोजी जा रही हैं

फ़ुल-टेक्स्ट सर्च से पहला मैच पाने के लिए, इस कोड का इस्तेमाल करें:

Query myQuery = new Query(feedUrl);
myQuery.setFullTextQuery("Tennis");
Feed myResultsFeed = myService.query(myQuery, Feed.class);
if (myResultsFeed.getEntries().size() > 0) {
  Entry firstMatchEntry = myResultsFeed.getEntries().get(0);
  String myEntryTitle = firstMatchEntry.getTitle().getPlainText();
}

इस उदाहरण में, सबसे पहले Query ऑब्जेक्ट बनाया गया है. इसमें ज़्यादातर यूआरएल और उससे जुड़े क्वेरी पैरामीटर शामिल होते हैं. GData के हर स्टैंडर्ड क्वेरी पैरामीटर के लिए, सेटर मेथड होता है. addCustomParameter तरीके का इस्तेमाल करके, किसी सेवा के लिए कस्टम क्वेरी पैरामीटर भी सेट किए जा सकते हैं.

Query बनाने के बाद, हम इसे सेवा के query तरीके से पास करते हैं. इससे हमें क्वेरी के नतीजों वाला फ़ीड मिलता है. इसके अलावा, यूआरएल को खुद भी बनाया जा सकता है. इसके लिए, फ़ीड यूआरएल में क्वेरी पैरामीटर जोड़ें. इसके बाद, getFeed तरीके को कॉल करें. हालांकि, query तरीके से अबस्ट्रैक्शन की एक उपयोगी लेयर मिलती है, ताकि आपको यूआरएल खुद न बनाना पड़े.

फ़ीड का getEntries तरीका, फ़ीड में मौजूद एंट्री की सूची दिखाता है. वहीं, getEntries().size फ़ीड में मौजूद एंट्री की संख्या दिखाता है.

इस मामले में, अगर क्वेरी से कोई नतीजा मिलता है, तो हम पहले मैचिंग नतीजे को Entry ऑब्जेक्ट को असाइन करते हैं. इसके बाद, हम Entry क्लास के getTitle().getPlainText तरीके का इस्तेमाल करके, एंट्री का टाइटल वापस पाते हैं और उसे टेक्स्ट में बदलते हैं.

ऊपर दिया गया कोड, Calendar में GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full?q=Tennis भेजने के बराबर है.

कैटगरी के हिसाब से क्वेरी करना

ध्यान दें: Google Calendar, इवेंट के साथ लेबल नहीं जोड़ता. इसलिए, यह उदाहरण Calendar के साथ काम नहीं करता.

उन सभी एंट्री वाला फ़ीड वापस पाने के लिए जो पहले की गई फ़ुल-टेक्स्ट खोज से मेल खाती हैं और किसी खास कैटगरी में हैं या जिनका कोई खास लेबल है, इस कोड का इस्तेमाल करें:

Category myCategory = new Category("by_liz");
CategoryFilter myCategoryFilter = new CategoryFilter(myCategory);
myQuery.addCategoryFilter(myCategoryFilter);
Feed myCategoryResultsFeed = myService.query(myQuery, Feed.class);

Category क्लास, बेशक, एक ऐसी कैटगरी को दिखाती है जिसका इस्तेमाल कैटगरी फ़िल्टर में किया जाना है. Query.CategoryFilter क्लास में कई कैटगरी हो सकती हैं. हालांकि, इस मामले में हम सिर्फ़ एक कैटगरी वाला फ़िल्टर बना रहे हैं.

इसके बाद, हम उस फ़िल्टर को मौजूदा क्वेरी में जोड़ते हैं. इसमें अब भी पिछले उदाहरण की फ़ुल-टेक्स्ट क्वेरी स्ट्रिंग शामिल है.

हम सेवा को क्वेरी भेजने के लिए, query तरीके का फिर से इस्तेमाल करते हैं.

अगर Calendar में कैटगरी के हिसाब से खोज करने की सुविधा होती, तो ऊपर दिया गया कोड, Calendar को GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/-/by_liz?q=Tennis भेजने के बराबर होता.

किसी आइटम को अपडेट करना

किसी मौजूदा आइटम को अपडेट करने के लिए, इस कोड का इस्तेमाल करें. इस उदाहरण में, हमने पहले से वापस लाई गई एंट्री के टाइटल को उसके पुराने टेक्स्ट ("डार्सी के साथ टेनिस") से बदलकर "अहम मीटिंग" कर दिया है.

retrievedEntry.setTitle(new PlainTextConstruct("Important meeting"));
URL editUrl = new URL(retrievedEntry.getEditLink().getHref());
EventEntry updatedEntry = myService.update(editUrl, myEntry);

सबसे पहले, हम उस एंट्री के लिए नया टाइटल सेट करते हैं जिसे हमने पहले फ़ेच किया था. इसके बाद, हम getEditLink तरीके का इस्तेमाल करके, एंट्री के लिए बदलाव करने वाला यूआरएल पाते हैं. इसके बाद, हम अपडेट की गई एंट्री भेजने के लिए, सेवा के update तरीके का इस्तेमाल करते हैं.

यह सेवा अपडेट की गई एंट्री दिखाती है. इसमें इस एंट्री के नए वर्शन का नया यूआरएल भी शामिल होता है. (एंट्री के वर्शन के बारे में ज़्यादा जानकारी के लिए, प्रोटोकॉल के रेफ़रंस दस्तावेज़ के ऑप्टिमिस्टिक कॉनकरेंसी सेक्शन पर जाएं.)

ऊपर दिया गया कोड, सेवा को PUT http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID भेजने के बराबर है. साथ ही, इसमें ओरिजनल एंट्री को बदलने के लिए नई एंट्री (एटम फ़ॉर्मैट में) भी शामिल है.

कोई आइटम मिटाना

अपडेट की गई एंट्री को मिटाने के लिए, इस कोड का इस्तेमाल करें:

URL deleteUrl = new URL(updatedEntry.getEditLink().getHref());
myService.delete(deleteUrl);

मिटाने के लिए इस्तेमाल किया जाने वाला यूआरएल, बदलाव करने वाले यूआरएल के जैसा ही होता है. इसलिए, यह उदाहरण पिछले उदाहरण से काफ़ी मिलता-जुलता है. हालांकि, इसमें हम update के बजाय delete तरीके का इस्तेमाल कर रहे हैं.

ऊपर दिया गया कोड, सेवा को DELETE http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID भेजने के बराबर है.

रेफ़रंस

क्लाइंट लाइब्रेरी की ओर से उपलब्ध कराई गई क्लास और तरीकों के बारे में रेफ़रंस जानकारी के लिए, Java क्लाइंट लाइब्रेरी का एपीआई रेफ़रंस (Javadoc फ़ॉर्मैट में) देखें.

वापस सबसे ऊपर जाएं