Java istemci kitaplığını kullanma

Bu belgede, Google Data API ("GData") sorguları göndermek ve döndürülen yanıtları yorumlamak için Java istemci kitaplığının nasıl kullanılacağı açıklanmaktadır.

Google, veri API'leri olan hizmetlerle etkileşim kurmak için çeşitli programlama dillerinde bir dizi istemci kitaplığı sağlar. Bu kitaplıkları kullanarak GData istekleri oluşturabilir, bunları bir hizmete gönderebilir ve yanıt alabilirsiniz.

Bu belgede, Java istemci kitaplığının kullanımıyla ilgili bazı genel bilgilerin yanı sıra yaygın kullanımlara dair bir dizi örnek verilmektedir.

Bu istemci kitaplığını kullanmak için Java 1.5'i çalıştırmanız gerekir.

Java istemci kitaplığını indirin.

Bu kılavuzdaki örneklerde Google Takvim API'si ele alınmaktadır ancak bu kılavuz, Takvim API'sinin kullanımıyla ilgili doğru veya güncel bir kılavuz değildir. Java istemci kitaplığını belirli bir hizmetin Data API'siyle kullanma hakkında bilgi için hizmete özel dokümanlara bakın. Örneğin, Takvim ile çalışıyorsanız Calendar Data API Geliştirici Kılavuzu'nu okuyun.

İçindekiler

  1. Kitle
  2. Veri modeline genel bakış
  3. Eğitici ve örnekler
    1. İstemcinizi oluşturma ve çalıştırma
    2. Feed isteğinde bulunma
    3. Yeni öğe ekleme
    4. Belirli bir girişi isteme
    5. Girişleri arama
    6. Kategoriye göre sorgulama
    7. Öğe güncelleme
    8. Öğe silme
  4. Reference

Kitle

Bu belge, GData hizmetleriyle etkileşim kurabilen istemci uygulamaları yazmak isteyen Java programcıları için hazırlanmıştır.

Bu belgede, Google Veri API'leri protokolünün temel kavramlarını bildiğiniz varsayılmaktadır. Ayrıca Java ile programlama yapmayı bildiğiniz de varsayılır.

İstemci kitaplığı tarafından sağlanan sınıflar ve yöntemler hakkında referans bilgileri için Java istemci kitaplığı API referansına (Javadoc biçiminde) bakın.

Bu belge, sırayla okunacak şekilde tasarlanmıştır. Her örnek, önceki örneklerin üzerine kurulmuştur.

Veri modeline genel bakış

Java istemci kitaplığı, Google Veri API'leri tarafından kullanılan öğeleri temsil etmek için bir dizi sınıf kullanır. Örneğin, <atom:feed> öğesine karşılık gelen bir Feed sınıfı vardır. Bu sınıf, giriş oluşturma, çeşitli alt öğelerin değerlerini alma ve ayarlama gibi yöntemlere sahiptir. <atom:entry> öğesine karşılık gelen bir Entry sınıfı da vardır. Google Veri API'lerinde tanımlanan her öğenin kendi sınıfı yoktur. Ayrıntılar için referans belgelerine bakın.

Kitaplık, Atom içeriğini otomatik olarak ayrıştırabilir ve Atom öğelerinin değerlerini uygun nesnelere yerleştirebilir. Örneğin, getFeed yöntemi bir feed alır, ayrıştırır ve sonuç değerleriyle bir Feed nesnesi döndürür.

Bir feed'i veya girişi bir hizmete göndermek için Feed veya Entry nesnesi oluşturur, ardından nesneyi otomatik olarak XML'ye çevirmek ve göndermek için bir kitaplık yöntemi (ör. insert yöntemi) çağırırsınız.

Tercih ederseniz XML'yi kendiniz ayrıştırabilir ve/veya oluşturabilirsiniz. Bunu yapmanın en kolay yolu Rome gibi uygun bir üçüncü taraf kitaplığı kullanmaktır.

Google Data API'nin XML söz dizimi genişletilebilir olduğu gibi, ilgili nesne modeli de genişletilebilir. Örneğin, istemci kitaplığı Google Veri ad alanında tanımlanan öğelere karşılık gelen sınıflar sağlar.

Eğitim ve örnekler

Aşağıdaki örneklerde, Java istemci kitaplığı kullanılarak çeşitli Data API isteklerinin nasıl gönderileceği gösterilmektedir.

Bu örnekler, daha somut hale getirmek için belirli bir hizmetle (Google Takvim) nasıl etkileşimde bulunulacağını gösterir. Bu örnekleri diğer hizmetlerde kullanabilmeniz için Takvim'in diğer Google hizmetlerinden farklı olduğu yerleri vurgulayacağız. Takvim hakkında daha fazla bilgi için Google Calendar Data API belgelerine bakın.

İstemcinizi oluşturma ve çalıştırma

Bu belgedeki örnekleri derlemek için aşağıdaki içe aktarma ifadelerini kullanmanız gerekir:

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;

Feed isteğinde bulunma

Google Calendar Data API belgesinde açıklandığı gibi, Calendar'a aşağıdaki HTTP isteğini göndererek bir Takvim feed'i isteğinde bulunabilirsiniz:

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

Elbette userID yerine kullanıcının e-posta adresini girmeniz gerekir. Ayrıntılar için Takvim dokümanına bakın. Bunun yerine, Takvim ile etkileşim kurmak için özel varsayılan URL'yi (Takvim dokümanında açıklandığı gibi) kullanabilirsiniz. Ancak bu dokümanda, kullanıcı kimliğini içeren özel tam özet akışı URL'si kullanılacaktır.

Ayrıca uygun kimlik doğrulama bilgilerini de sağlamanız gerekir. Bu örnek ile Takvim dokümanındaki ilk örnek arasındaki temel farklar şunlardır: (1) Bu örnekte kimlik doğrulama yer alır ve (2) bu örnekte Takvim'e özgü CalendarService sınıfı yerine daha genel olan GoogleService sınıfı kullanılır.

Burada kullandığımız kimlik doğrulama sisteminin ("Yüklü Uygulamalar İçin Google Kimlik Doğrulaması" olarak bilinir) yalnızca masaüstü istemcileri gibi yüklü istemci uygulamalarında kullanıma uygun olduğunu, web uygulamalarında kullanıma uygun olmadığını unutmayın. Kimlik doğrulama hakkında daha fazla bilgi için Google Hesabı Kimlik Doğrulaması belgesine bakın.

Java istemci kitaplığını kullanarak takvim feed'i istemek için "liz@gmail.com" e-posta adresine ve "mypassword" şifresine sahip bir kullanıcı için aşağıdaki kodu kullanın:

// 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 sınıfı, bir GData hizmetine istemci bağlantısını (kimlik doğrulama ile) temsil eder. İstemci kitaplığını kullanarak bir hizmete sorgu göndermeyle ilgili genel prosedür aşağıdaki adımlardan oluşur:

  1. Uygun URL'yi edinin veya oluşturun.
  2. Bir hizmete veri gönderiyorsanız (örneğin, yeni bir giriş ekliyorsanız) ham verileri istemci kitaplığı sınıflarını kullanarak nesnelere dönüştürün. (Bu adım, bu örnekte yaptığımız gibi yalnızca feed isteğinde bulunuyorsanız geçerli değildir.)
  3. Hizmet adını (ör. Takvim için "cl") ve uygulamanızın adını (companyName-applicationName-versionID biçiminde) ayarlayarak yeni bir GoogleService örneği oluşturun.
  4. Uygun kimlik bilgilerini ayarlayın.
  5. Kitaplığın döndürülen feed'leri doğru şekilde ayrıştırabilmesi için istemci kitaplığına feed'in hangi uzantıları kullanacağını belirtin.
  6. İsteği göndermek ve sonuçları almak için bir yöntemi çağırın.

setUserCredentials yöntemi, istemcinizin sorguyu gönderdiği kullanıcının kimliğini ve şifresini belirtir. Bu belgedeki örneklerde "Yüklü Uygulamalar İçin Kimlik Doğrulama" kimlik doğrulama sistemi kullanılmaktadır. Kimlik doğrulama sistemleri hakkında daha fazla bilgi için Google Hesabı Kimlik Doğrulaması dokümanlarına bakın.

Kimlik bilgilerini ayarladıktan sonra declareExtensions yöntemini çağırarak feed'in hangi uzantıları kullanacağını belirtirsiniz. Bu durumda, feed'in bir etkinlik feed'i olduğunu ve dolayısıyla Etkinlik türü tarafından tanımlanan uzantıları kullanacağını belirtiyoruz.

Bir feed'in tamamını istemek için getFeed yöntemini çağırırsınız. Bu yöntem bir URL alır ve o URL'de bulunan feed'in tamamını döndürür. Daha ayrıntılı sorguların nasıl gönderileceğini bu belgenin ilerleyen bölümlerinde göstereceğiz.

GoogleService sınıfının diğer yöntemleri gibi getFeed de kimlik doğrulamayı ve yönlendirmeleri gerektiği gibi işler.

Yeni öğe ekleme

Yeni bir takvim etkinliği oluşturmak için aşağıdaki kodu kullanabilirsiniz:

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

URL'yi ayarladıktan sonra bir EventEntry nesnesi oluştururuz. EventEntry, BaseEntry soyut temel sınıfından türetilir. Bu sınıf, <atom:entry> öğesini temsil eden Entry sınıfının da üst sınıfıdır.

EventEntry sınıfı bir Etkinlik türünü temsil eder. Daha fazla bilgi için Türler belgesine bakın. Takvim dışındaki hizmetler için döndürülen girişi bir EventEntry nesnesi yerine bir Entry nesnesine atayabilirsiniz.

Giriş başlığı, metni çeşitli biçimlerde (düz metin, HTML veya XHTML) tutan bir sınıf olan TextConstruct'dır. Giriş içeriği, XML ve ikili veriler dahil olmak üzere düz metin veya diğer içerik biçimlerini barındırabilen bir sınıf olan Content nesnesiyle temsil edilir. (Ancak setContent yöntemi TextConstruct değerini de kabul edebilir.)

Her yazar ad, URI ve e-posta adresi olarak gösterilir. (Bu örnekte URI'yi dahil etmiyoruz.) Girişin getAuthors().add yöntemini çağırarak girişe yazar ekleyebilirsiniz.

Önceki örnekte oluşturduğumuz GoogleService nesnesini kullanıyoruz. Bu durumda, çağrılacak yöntem insert'dır. Bu yöntem, belirtilen ekleme URL'sine bir öğe gönderir.

Hizmet, yeni oluşturulan girişi döndürür. Bu giriş, sunucu tarafından oluşturulan ek öğeler (ör. giriş için düzenleme URL'si) içerebilir.

HTTP durum kodları istisna olarak döndürülür.

Yukarıdaki kod, POST http://www.google.com/calendar/feeds/liz@gmail.com/private/full göndermeye (uygun kimlik doğrulama ile) ve Etkinlik türünde bir giriş sağlamaya eşdeğerdir.

Belirli bir girişi isteme

Aşağıdaki kod, önceki örnekte eklediğiniz belirli girişi istemenize olanak tanır.

Bu örnekler dizisi bağlamında, takvim zaten eklenen girişi döndürdüğü için bu girişi almak gerçekten gerekli değildir. Ancak bir girişin URI'sini bildiğiniz her durumda aynı teknik uygulanabilir.

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

Eklenen giriş, girişin URL'sini içeren bir Link nesnesi döndüren bir yönteme (getSelfLink) sahiptir. Link sınıfında, URL'yi String olarak döndüren bir getHref yöntemi bulunur. Bu yöntemden bir URL nesnesi oluşturabiliriz.

Ardından, girişi almak için hizmetin getEntry yöntemini çağırmamız yeterlidir.

EventEntry.class parametresini getEntry olarak verdiğimizi unutmayın. Bu, hizmetin yalnızca düz bir giriş yerine özellikle bir Etkinlik döndürmesini beklediğimizi gösterir. Takvim dışındaki hizmetler için bunun yerine Entry.class iletebilirsiniz.

Yukarıdaki kod, GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID değerinin uygun kimlik doğrulamasıyla Takvim'e gönderilmesine eşdeğerdir.

Girişleri arama

Tam metin aramasından ilk eşleşmeyi almak için aşağıdaki kodu kullanın:

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

Bu örnekte, çoğunlukla bir URL'nin yanı sıra ilişkili sorgu parametrelerinden oluşan bir Query nesnesi oluşturularak başlanır. Standart GData sorgu parametrelerinin her birinin bir ayarlayıcı yöntemi vardır. Ayrıca, addCustomParameter yöntemini kullanarak belirli bir hizmet için özel sorgu parametreleri de ayarlayabilirsiniz.

Query oluşturulduktan sonra, sorgu sonuçlarını içeren bir feed döndüren hizmetin query yöntemine iletilir. Alternatif bir yaklaşım, URL'yi kendiniz oluşturmak (feed URL'sine sorgu parametreleri ekleyerek) ve ardından getFeed yöntemini çağırmak olabilir. Ancak query yöntemi, URL'yi kendiniz oluşturmak zorunda kalmamanız için yararlı bir soyutlama katmanı sağlar.

Feed'in getEntries yöntemi, feed'deki girişlerin listesini döndürür. getEntries().size ise feed'deki girişlerin sayısını döndürür.

Bu durumda, sorgu herhangi bir sonuç döndürürse eşleşen ilk sonucu bir Entry nesnesine atarız. Ardından, girişin başlığını almak ve metne dönüştürmek için Entry sınıfının getTitle().getPlainText yöntemini kullanırız.

Yukarıdaki kod, Takvim'e GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full?q=Tennis göndermeye eşdeğerdir.

Kategoriye göre sorgulama

Not: Google Takvim, etiketleri etkinliklerle ilişkilendirmediği için bu örnek Takvim ile çalışmaz.

Önceki tam metin aramasıyla eşleşen ve belirli bir kategoride olan veya belirli bir etikete sahip tüm girişlerden oluşan bir feed'i almak için aşağıdaki kodu kullanın:

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

Category sınıfı, kategori filtresinde kullanılacak bir kategoriyi temsil eder. Query.CategoryFilter sınıfı birden fazla kategori içerebilir ancak bu durumda yalnızca bir kategori içeren bir filtre oluşturuyoruz.

Ardından, bu filtreyi önceki örnekteki tam metin sorgu dizesini hâlâ içeren mevcut sorguya ekliyoruz.

Sorguyu hizmete göndermek için yine query yöntemini kullanırız.

Takvim'de kategori aramasına izin verilseydi yukarıdaki kod, Takvim'e GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/-/by_liz?q=Tennis göndermeye eşdeğer olurdu.

Öğe güncelleme

Mevcut bir öğeyi güncellemek için aşağıdaki kodu kullanın. Bu örnekte, daha önce alınan girişin başlığını eski metninden ("Darcy ile tenis") "Önemli toplantı" olarak değiştiriyoruz.

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

Öncelikle, daha önce getirdiğimiz giriş için yeni bir başlık belirleriz. Ardından, getEditLink yöntemini kullanarak girişin düzenleme URL'sini alırız. Ardından, güncellenen girişi göndermek için hizmetin update yöntemini çağırırız.

Hizmet, bu girişin yeni sürümüne ait yeni bir URL de dahil olmak üzere güncellenmiş girişi döndürür. (Giriş sürümleri hakkında daha fazla bilgi için protokol referans belgesinin Optimistic concurrency (İyimser eşzamanlılık) bölümüne bakın.)

Yukarıdaki kod, orijinal girişi değiştirmek için yeni girişle (Atom biçiminde) birlikte hizmete PUT http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID göndermeye kabaca eşdeğerdir.

Öğe silme

Güncellenen girişi silmek için aşağıdaki kodu kullanın:

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

Silme için kullanılacak URL, düzenleme URL'siyle aynıdır. Bu nedenle, update yerine delete yöntemini çağırmamız dışında bu örnek, önceki örneğe çok benzer.

Yukarıdaki kod, hizmete DELETE http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID göndermeye kabaca eşdeğerdir.

Referans

İstemci kitaplığı tarafından sağlanan sınıflar ve yöntemler hakkında referans bilgileri için Java istemci kitaplığı API referansına (Javadoc biçiminde) bakın.

Başa dön