Menggunakan Library Klien Java

Dokumen ini menjelaskan cara menggunakan library klien Java untuk mengirim kueri Google Data API ("GData") dan menafsirkan respons yang ditampilkan.

Google menyediakan serangkaian library klien, dalam berbagai bahasa pemrograman, untuk berinteraksi dengan layanan yang memiliki API data. Dengan menggunakan library ini, Anda dapat membuat permintaan GData, mengirimkannya ke layanan, dan menerima respons.

Dokumen ini memberikan beberapa informasi umum tentang penggunaan library klien Java, beserta serangkaian contoh penggunaan umum.

Untuk menggunakan library klien ini, Anda harus menjalankan Java 1.5.

Download library klien Java.

Contoh dalam panduan ini merujuk ke Google Calendar API, tetapi panduan ini bukan panduan yang akurat atau terbaru untuk menggunakan Calendar API. Untuk mengetahui informasi tentang penggunaan library klien Java dengan Data API layanan tertentu, lihat dokumentasi khusus layanan. Misalnya, jika Anda bekerja dengan Kalender, baca Panduan Developer Calendar Data API.

Daftar Isi

  1. Penonton
  2. Ringkasan model data
  3. Tutorial dan contoh
    1. Membangun dan menjalankan klien
    2. Meminta feed
    3. Menyisipkan item baru
    4. Meminta entri tertentu
    5. Menelusuri entri
    6. Mengajukan kueri menurut kategori
    7. Memperbarui item
    8. Menghapus item
  4. Referensi

Audiens

Dokumen ini ditujukan untuk programmer Java yang ingin menulis aplikasi klien yang dapat berinteraksi dengan layanan GData.

Dokumen ini mengasumsikan bahwa Anda memahami ide umum di balik protokol Google Data API. Selain itu, Anda dianggap telah mengetahui cara memprogram di Java.

Untuk informasi referensi tentang class dan metode yang disediakan oleh library klien, lihat referensi API library klien Java (dalam format Javadoc).

Dokumen ini dirancang untuk dibaca secara berurutan; setiap contoh dibangun berdasarkan contoh sebelumnya.

Ringkasan model data

Library klien Java menggunakan serangkaian class untuk merepresentasikan elemen yang digunakan oleh Google Data API. Misalnya, ada class Feed, yang sesuai dengan elemen <atom:feed>; class ini memiliki metode untuk membuat entri, mendapatkan dan menetapkan nilai berbagai sub-elemen, dan sebagainya. Ada juga class Entry, yang sesuai dengan elemen <atom:entry>. Tidak setiap elemen yang ditentukan di Google Data API memiliki class-nya sendiri; untuk mengetahui detailnya, lihat dokumentasi referensi.

Library dapat secara otomatis mengurai konten Atom dan menempatkan nilai elemen Atom ke dalam objek yang sesuai. Misalnya, metode getFeed mendapatkan feed, menguraikannya, dan menampilkan objek Feed dengan nilai yang dihasilkan.

Untuk mengirimkan feed atau entri ke layanan, Anda membuat objek Feed atau Entry, lalu memanggil metode library (seperti metode insert) untuk menerjemahkan objek secara otomatis ke XML dan mengirimkannya.

Anda dapat mengurai dan/atau membuat XML sendiri jika mau; cara termudah untuk melakukannya adalah dengan library pihak ketiga yang sesuai seperti Rome.

Seperti sintaksis XML Google Data API yang dapat diperluas, model objek yang sesuai juga dapat diperluas. Misalnya, library klien menyediakan class yang sesuai dengan elemen yang ditentukan dalam namespace Data Google.

Tutorial dan contoh

Contoh berikut menunjukkan cara mengirim berbagai permintaan Data API menggunakan library klien Java.

Untuk membuatnya lebih konkret, contoh ini menunjukkan cara berinteraksi dengan layanan tertentu: Google Kalender. Kami akan menunjukkan tempat-tempat yang membuat Kalender berbeda dari layanan Google lainnya, untuk membantu Anda menyesuaikan contoh ini agar dapat digunakan dengan layanan lain. Untuk mengetahui informasi selengkapnya tentang Kalender, lihat dokumentasi Google Calendar Data API.

Membangun dan menjalankan klien

Untuk mengompilasi contoh dalam dokumen ini, Anda harus menggunakan pernyataan impor berikut:

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;

Meminta feed

Seperti yang dijelaskan dalam dokumen Google Calendar Data API, Anda dapat meminta feed Kalender dengan mengirim permintaan HTTP berikut ke Kalender:

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

Tentu saja, Anda harus mengganti userID dengan alamat email pengguna; lihat dokumen Kalender untuk mengetahui detailnya. Sebagai gantinya, Anda dapat menggunakan URL default khusus untuk berinteraksi dengan Kalender (seperti yang dijelaskan dalam dokumen Kalender), tetapi dalam dokumen ini, kita akan menggunakan URL feed lengkap pribadi, yang berisi ID pengguna.

Anda juga harus memberikan autentikasi yang sesuai. Perbedaan utama antara contoh ini dan contoh pertama dalam dokumen Kalender adalah (1) contoh ini mencakup autentikasi, dan (2) contoh ini menggunakan class GoogleService yang lebih umum, bukan class CalendarService khusus Kalender.

Perhatikan bahwa sistem autentikasi yang kita gunakan di sini (dikenal sebagai "Autentikasi Google untuk Aplikasi yang Diinstal") hanya cocok untuk digunakan dalam aplikasi klien yang diinstal seperti klien desktop, bukan untuk digunakan dalam aplikasi web. Untuk mengetahui informasi selengkapnya tentang autentikasi, lihat dokumentasi Autentikasi Akun Google.

Untuk meminta feed Kalender menggunakan library klien Java, bagi pengguna dengan alamat email "liz@gmail.com" dan sandi "mypassword", gunakan kode berikut:

// 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);

Class GoogleService mewakili koneksi klien (dengan autentikasi) ke layanan GData. Prosedur umum untuk mengirim kueri ke layanan menggunakan library klien terdiri dari langkah-langkah berikut:

  1. Dapatkan atau buat URL yang sesuai.
  2. Jika Anda mengirim data ke layanan (misalnya, jika Anda menyisipkan entri baru), ubah data mentah menjadi objek menggunakan class library klien. (Langkah ini tidak berlaku jika Anda hanya meminta feed, seperti yang kami lakukan dalam contoh ini.)
  3. Buat instance GoogleService baru, tetapkan nama layanan (seperti "cl" untuk Kalender) dan nama aplikasi Anda (dalam bentuk companyName-applicationName-versionID).
  4. Tetapkan kredensial yang sesuai.
  5. Tunjukkan kepada library klien ekstensi yang akan digunakan feed, sehingga library dapat mem-parsing feed yang ditampilkan dengan benar.
  6. Panggil metode untuk mengirim permintaan dan menerima hasil apa pun.

Metode setUserCredentials menentukan ID dan sandi pengguna yang atas nama pengguna tersebut klien Anda mengirimkan kueri. Contoh dalam dokumen ini menggunakan sistem autentikasi "Autentikasi untuk Aplikasi yang Diinstal". Untuk mengetahui informasi selengkapnya tentang sistem autentikasi, lihat dokumentasi Autentikasi Akun Google.

Setelah menetapkan kredensial, Anda menunjukkan ekstensi mana yang akan digunakan feed dengan memanggil metode declareExtensions. Dalam hal ini, kita menyatakan bahwa feed adalah feed Peristiwa, dan dengan demikian akan menggunakan ekstensi yang ditentukan oleh jenis Peristiwa.

Untuk meminta seluruh feed, Anda memanggil metode getFeed, yang mengambil URL dan menampilkan seluruh feed yang ditemukan di URL tersebut. Kami akan menunjukkan cara mengirim kueri yang lebih spesifik nanti dalam dokumen ini.

Seperti metode lain dari class GoogleService, getFeed menangani autentikasi dan pengalihan sesuai kebutuhan.

Menyisipkan item baru

Untuk membuat acara kalender baru, Anda dapat menggunakan kode berikut:

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);

Setelah menetapkan URL, kita membuat objek EventEntry; EventEntry berasal dari class dasar abstrak BaseEntry, yang juga merupakan class induk untuk class Entry, yang merepresentasikan elemen <atom:entry>.

Class EventEntry merepresentasikan jenis Peristiwa; untuk mengetahui informasi selengkapnya, lihat dokumen Jenis. Untuk layanan selain Kalender, Anda dapat menetapkan entri yang ditampilkan ke objek Entry, bukan objek EventEntry.

Judul entri adalah TextConstruct, sebuah class yang menyimpan teks dalam berbagai bentuk (teks biasa, HTML, atau XHTML). Konten entri diwakili oleh objek Content, yaitu class yang dapat menyimpan teks biasa atau bentuk konten lainnya, termasuk XML dan data biner. (Namun, metode setContent juga dapat menerima TextConstruct.)

Setiap penulis ditampilkan sebagai nama, URI, dan alamat email. (Dalam contoh ini, kita tidak menyertakan URI.) Anda menambahkan penulis ke entri dengan memanggil metode getAuthors().add entri.

Kita menggunakan objek GoogleService yang sama dengan yang kita buat dalam contoh sebelumnya. Dalam hal ini, metode yang akan dipanggil adalah insert, yang mengirimkan item ke URL penyisipan yang ditentukan.

Layanan ini menampilkan entri yang baru dibuat, yang mungkin berisi elemen tambahan yang dihasilkan server, seperti URL pengeditan untuk entri.

Kode status HTTP ditampilkan sebagai pengecualian.

Kode di atas setara dengan mengirim POST http://www.google.com/calendar/feeds/liz@gmail.com/private/full (dengan autentikasi yang tepat) dan memberikan entri dalam bentuk jenis Peristiwa.

Meminta entri tertentu

Kode berikut memungkinkan Anda meminta entri spesifik yang Anda sisipkan dalam contoh sebelumnya.

Dalam konteks rangkaian contoh ini, pengambilan entri tersebut sebenarnya tidak diperlukan, karena Kalender telah menampilkan entri yang dimasukkan; tetapi teknik yang sama dapat diterapkan kapan pun Anda mengetahui URI untuk suatu entri.

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

Entri yang disisipkan memiliki metode, getSelfLink, yang menampilkan objek Link yang menyertakan URL entri. Class Link memiliki metode getHref yang menampilkan URL sebagai String, yang dapat kita gunakan untuk membuat objek URL.

Kemudian, kita hanya perlu memanggil metode getEntry layanan untuk mendapatkan entri.

Perhatikan bahwa kita memberikan EventEntry.class sebagai parameter ke getEntry, yang menunjukkan bahwa kita secara khusus mengharapkan layanan menampilkan Peristiwa, bukan hanya entri biasa. Untuk layanan selain Kalender, Anda mungkin hanya meneruskan Entry.class.

Kode di atas setara dengan mengirim GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID ke Kalender, dengan autentikasi yang tepat.

Menelusuri entri

Untuk mengambil kecocokan pertama dari penelusuran teks lengkap, gunakan kode berikut:

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();
}

Contoh ini dimulai dengan membuat objek Query, yang sebagian besar terdiri dari URL dan parameter kueri terkait. Setiap parameter kueri GData standar memiliki metode penyetel. Anda juga dapat menetapkan parameter kueri kustom untuk layanan tertentu, menggunakan metode addCustomParameter.

Setelah membuat Query, kita meneruskannya ke metode query layanan, yang menampilkan feed yang berisi hasil kueri. Pendekatan alternatifnya adalah membuat URL sendiri (dengan menambahkan parameter kueri ke URL feed), lalu memanggil metode getFeed, tetapi metode query memberikan lapisan abstraksi yang berguna sehingga Anda tidak perlu membuat URL sendiri.

Metode getEntries feed menampilkan daftar entri dalam feed; getEntries().size menampilkan jumlah entri dalam feed.

Dalam hal ini, jika kueri menampilkan hasil apa pun, kita akan menetapkan hasil yang cocok pertama ke objek Entry. Kemudian, kita menggunakan metode getTitle().getPlainText class Entry untuk mengambil judul entri dan mengonversinya menjadi teks.

Kode di atas setara dengan mengirim GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full?q=Tennis ke Kalender.

Mengirim kueri menurut kategori

Catatan: Google Kalender tidak mengaitkan label dengan acara, jadi contoh ini tidak berfungsi dengan Kalender.

Untuk mengambil feed yang terdiri dari semua entri yang cocok dengan penelusuran teks lengkap sebelumnya dan yang berada dalam kategori tertentu atau memiliki label tertentu, gunakan kode berikut:

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

Tentu saja, class Category mewakili kategori yang akan digunakan dalam filter kategori. Class Query.CategoryFilter dapat berisi beberapa kategori, tetapi dalam kasus ini kita membuat filter dengan hanya satu kategori.

Kemudian, kita menambahkan filter tersebut ke kueri yang ada, yang masih berisi string kueri teks lengkap dari contoh sebelumnya.

Kita kembali menggunakan metode query untuk mengirim kueri ke layanan.

Jika Kalender mengizinkan penelusuran kategori, kode di atas akan setara dengan mengirim GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/-/by_liz?q=Tennis ke Kalender.

Memperbarui item

Untuk memperbarui item yang ada, gunakan kode berikut. Dalam contoh ini, kita mengubah judul entri yang sebelumnya diambil dari teks lamanya ("Tennis with Darcy") menjadi "Important meeting".

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

Pertama, kita menetapkan judul baru untuk entri yang kita ambil sebelumnya. Kemudian, kita mendapatkan URL pengeditan untuk entri, menggunakan metode getEditLink. Kemudian, kita memanggil metode update layanan untuk mengirim entri yang diperbarui.

Layanan menampilkan entri yang diperbarui, termasuk URL baru untuk versi baru entri ini. (Untuk mengetahui informasi selengkapnya tentang versi entri, lihat bagian Konkurensi optimis dalam dokumen referensi protokol.)

Kode di atas kurang lebih setara dengan mengirim PUT http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID ke layanan, beserta entri baru (dalam format Atom) untuk menggantikan entri asli.

Menghapus item

Untuk menghapus entri yang diperbarui, gunakan kode berikut:

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

URL yang digunakan untuk penghapusan sama dengan URL pengeditan, jadi contoh ini sangat mirip dengan contoh sebelumnya, kecuali tentu saja kita memanggil metode delete, bukan update.

Kode di atas kurang lebih setara dengan mengirim DELETE http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID ke layanan.

Referensi

Untuk informasi referensi tentang class dan metode yang disediakan oleh library klien, lihat referensi API library klien Java (dalam format Javadoc).

Kembali ke atas