Google Data API 使用体验 (1)-- Calendar篇

Google的API也出了有好久了..一直没用过..前段日子看到连GoogleCL这样的神器都出来了..想API应该已经比较完善了吧..就心痒痒一直想试试..咱有空也写个java版的GoogleCL出来..呵呵..一捱已经到了暑假..才研究了个calendar的简单使用..惭愧啊.

先上来记一笔..其实我个人一直很想先研究doc的..因为现有的客户端比较烂..想自己做个好用点的..但还是先搞了calendar..至于原因呢..在后面的几篇日志里应该会有个交代的..其实网上关于这些API研究的文已经很多了..写不写可能无所谓..但从我个人学习的经验总结下来..觉得弯路还是走的不少的..所以还是写一些心得出来比较好..(废话好多..)

以下为挑重点介绍下..原始的可以参看GoogleAPI..

例如:http://code.google.com/intl/zh-CN/apis/calendar/data/2.0/developers_guide_java.html

 

1.EventEntry元素

日历里的每个事件就是一个event..一般可以用一个EventEntry来表示..EventEntry主要有以下几个重要的属性:

1)PlainTextConstruct title

2)Person author

3)When time

4)Where location

5)PlainTextConstruct content

6)Recurrence recu

1)title顾名思义就是事件的名称或者说内容..可以是一个简单的String..

2)author是事件的作者..Person这个类中包含一个String的作者名字,还有Google帐号的username等信息..但实际上..我觉得可能是由于google服务本身的漏洞..这些信息都没有实际的作用..可以忽略不设也就是让他自动设置..

3)time也就是本次事件的起始时间.注意!:在一个Event里面只能有When或者Recurrence中的一个!如果是使用When..需要设置startTime和endTime这2个属性..他们都是DataTime类型的..也就是设置这个Event的起始和结束时间,并且这个Event显然是只执行一次的..如果你要添加的是一个周期性的Event..就不好用When了..需要使用Recurrence..这个后面再说..而这里的DataTime是需要这样形式的String来设置的:

例如:  2006-04-17T17:00:00-08:00

yyyy-MM-dd + "T" + hh:mm:ss + TimeZone

4)location即事件发生的地点..Where类也有rel/label/where三个String属性..同前所述..rel和label也不好用..可以不设..where就是你需要定义的地点..

5)content说明内容..即对本事件的补充信息..和title的使用方法相同.

6)recu...这是个好东西啊.花了我一个下午才大致研究出点眉目..说简单了..这就是用来设置事件的周期属性的..例如我每周一要上体育课..我只要生成一个上体育课的事件..然后设置Recurrence让他每周一都重复一次..还可以设置重复的次数或者截止日期..这样一学期的所有体育课就是一个Event了..而不是每周一节课都是一个Event..那样就要多出10多个Event了..而且不好管理..而要真正的掌握Recurrence的使用规则却不是很简单..这里先有个简单的映象..放到文末再详细介绍..

了解了这些元素..我们就可以根据需要来创建一个Event了..简单的代码如下:

public EventEntry createEventWhen(String title, String content, String author, String stime, String etime, String where) {
        EventEntry myEntry = new EventEntry();
        if (title != null) {
            myEntry.setTitle(new PlainTextConstruct(title));
        }

        if (content != null) {
            if (!content.startsWith(GCalendar.DefaultContentLabel)) {
                content = GCalendar.DefaultContentLabel + GCalendar.DefaultContentVersion + " " + content;
            }
            myEntry.setContent(new PlainTextConstruct(content));
        }

        if (author != null) {
            Person myAuthor = new Person(author, null, username);
            myEntry.getAuthors().add(myAuthor);
        }

        DateTime startTime = null;
        DateTime endTime = null;
        if (stime != null) {
            startTime = DateTime.parseDateTime(stime);//"2006-04-17T15:00:00-08:00"
        }
        if (etime != null) {
            endTime = DateTime.parseDateTime(etime);//"2006-04-17T17:00:00-08:00"
        }
        When eventTimes = new When();
        eventTimes.setStartTime(startTime);
        eventTimes.setEndTime(endTime);
        myEntry.addTime(eventTimes);

        if (where != null) {
            Where myWhere = new Where(GCalendar.DefaultWhereRel, GCalendar.DefaultWherelabel, where);
            myEntry.addLocation(myWhere);
        }

        return myEntry;
    }

 

public EventEntry createEventRecurrence(String title, String content, String author, String recu, String where) {
        EventEntry myEntry = new EventEntry();
        if (title != null) {
            myEntry.setTitle(new PlainTextConstruct(title));
        }

        if (content != null) {
            if (!content.startsWith(GCalendar.DefaultContentLabel)) {
                content = GCalendar.DefaultContentLabel + GCalendar.DefaultContentVersion + " " + content;
            }
            myEntry.setContent(new PlainTextConstruct(content));
        }

        if (author != null) {
            Person myAuthor = new Person(author, null, username);
            myEntry.getAuthors().add(myAuthor);
        }

        if (recu == null) {
            recu = new String("");
        }
        Recurrence rec = new Recurrence();
        rec.setValue(recu); 
        myEntry.setRecurrence(rec);

        //myEntry.addTime(null);

        if (where != null) {
            Where myWhere = new Where(GCalendar.DefaultWhereRel, GCalendar.DefaultWherelabel, where);
            myEntry.addLocation(myWhere);
        }

        return myEntry;
    }

 

2.CalendarService

1)创建CalendarService:

CalendarService myService = new CalendarService(GCalendar.CLIENTNAME);

其中GCalendar.CLIENTNAME可以是自己定义的客户端的名字..然后需要设置客户端相关:

myService.setProtocolVersion(CalendarService.Versions.V1);

这里我们选用的是v1也就是gdata-api 1.0的版本..其实2.0早就出来了..我所使用的lib也都是2.0的..但是也是由于google服务端的bug..2.0有很多的问题..我们只好先设置成1.0的才可以顺利的使用大部分功能..

2)设置Google帐号用户名和密码:

myService.setUserCredentials(username, password);

这一步不光会设置用户名和密码到客户端..还会自动网络验证..如果验证不通过..会抛出错误..

3)将Event添加到日历:EventEntry insertEvent(EventEntry entry)

URL postUrl= new URL(new String(GCalendar.DefaultURL).replaceFirst("username", username));
EventEntry insertedEntry = myService.insert(postUrl, entry);

entry即为要添加的EventEntry..GCalendar.DefaultURL =

http://www.google.com/calendar/feeds/username/private/full;

把这里的username部分用用户的邮件地址,例如:[e-mail]替换后生成的URL即为用户的默认日历的feed地址...所以上述添加日历的过程实际上就是将要添加的EventEntry  POST 到用户日历的URL的过程..

4)查询日历事件:EventFeed queryEvent(String key)

Query myQuery=new Query(new URL(new String(GCalendar.DefaultURL).replaceFirst("username", username)));

myQuery.setMaxResults(max);//设置一次查找最大的返回条目数

myQuery.setFullTextQuery(key);//设置查找内容的关键字

EventFeed myFeed = myService.query(myQuery, EventFeed.class);

查找返回结果..myFeed.getEntries()即可得到一个符合查找条件的List..

5)更改日历事件:EventEntry updateEvent(EventEntry entry1, EventEntry entry2)

URL updateUrl= new URL(entry1.getEditLink().getHref());//entry1为要更改的event

updateEntry = myService.update(updateUrl, entry2);//entry2为更改后的event

6)删除日历事件:void deleteEvent(EventEntry entry)

URL deleteUrl = new URL(entry.getEditLink().getHref());//获得要删除的条目的link..

myService.delete(deleteUrl);//删除..

 

以上基本的函数应该就能满足简单的日历应用了..

 

补充(1):Recurrence规则的设置

关于Recurrence的定义可以参照 RFC2445

主要就是Recurrence有一个String value需要设置..

一个例子:

DTSTART;TZID=Asia/Shanghai:20100725T160000

DTEND;TZID=Asia/Shanghai:20100725T180000

RRULE:FREQ=WEEKLY;COUNT=10;INTERVAL=2;BYDAY=SU

上述所表达的规则的意思是:从上海时区的2010年7月25号16点开始到当日18点结束的一个事件,每隔一星期(即每2星期发生一次)的星期日重复一次事件,共发生10次.

DTATRT为事件开始的时间..DTEND为结束时间..TZID为时区的ID,可以通过

String TZID = TimeZone.getDefault().getID();来得到当前系统默认的时区的ID信息..RRULE是最重要的部分..决定事件的重复规律..

1)FREQ就是重复频率..YEARLY..MONTHLY..DAYLY等等..

2)可以是COUNT或者UNTIL..只可选其中一个..COUNT是事件总共发生的次数..UNTIL是周期时间结束的时间..他们决定了事件重复发生的结束条件..

3)附加选项信息..比如INTERVAL设定间隔..BYDAY按照一星期来设置重复的日子..详细的可以查看文档...呵呵..我这里简单能用就行了..

又一个例子:

DTSTART;TZID=Asia/Shanghai:20100725T160000

DURATION:3H

RRULE:FREQ=MONTHLY;UNTIL=20101010;INTERVAL=1;

上述所表达的意思是:从上海时区的2010年7月25号16点开始的事件,经历3个小时后结束,按照每月一次的频率重复发生直到2010年10月10号结束重复.

这里我们注意到用了DURATION这个选项来代替DTEND..意思应该是一目了然了吧..值的话可以是 3600S / 60M / 1H ..要注意的是两者只能选其一..即要么规定结束的时刻..要么规定时间持续的时间..

频率是每月一次..直到UNTIL所规定的日子结束..间隔为1..不规定BYDAY之类的重复日的话是按照重复频率和初始事件自动计算的..

以上..这2种基本的用法演示应该能满足简单使用需求了..

再讲一个小问题:即当FREQ选择的是MONTHLY按月重复的时候..假设我第一次事件是在1月31号..而2月只有28天或者29天..没有31天..那么按照正常的设置..是要2月31号才会重复触发事件..没有这一天的话就会自动忽略过去了..所以虽然设置的是按月重复..但实际上第二次发生是在3月31号了..同理..4月也不会发生..因为只有30天..那么就出现偏差了..假设我们的本意是要本月最后的一天发生的..每个月必须发生一次.那么..用如下的语句可以解决:

FREQ=MONTHLY;BYMONTHDAY=28,29,30;BYSETPOS=-1

奥妙就在这个BYSETPOS=-1..呵呵..大家都懂得吧..

 

以上..