博客园_克伟的博客

我们的创业步伐：我们的产品

2011-07-04T08:40:00Z

好久没写博客了，距离《我们的创业步伐》这篇文章有半年了，回首这半年，发现居然不知道说什么了，道不出其中的滋味。

坦白的说我们已经到了生死存亡的时刻了，想想我们的创业历程，刚开始的想法、现在的想法、我们的困难、我们的团队，可以这么概况下：

最初我们喜欢把创业比喻成游泳，不亲自下水游是没办法学会游泳的，但是你也要做好被淹的半死的准备。

穷人做事有穷人的办法，实在没办法的情况下白米饭也能养出来一个产品。

做有意见、有价值的东西。

不变的是信念、原则，变的是经验、能力、机遇。

少一些冲动，多一些冷静，少一些急躁，多一些坚持。我只会越挫越勇。一些事情我希望想的更清楚一些。

看看我们做的产品吧。

第一个产品：MCOS，基于通讯录的IM

最初的MCOS的Windows Mobile客户端：

你不会看到这个产品了，我们最开始做这个产品时Kik Messager、WhatsApp没有崛起，没有语音消息和群组消息，国内没有米聊、没有微信，个信、友信、速聊等等都还没有，当类Kik的应用遍地都是时我们放弃了，我们需要一个真正的有所差异的、解决用户某个痛的东西。

虽然MCOS死掉了，但是她的灵魂仍然在，她的灵魂将以不同的形态在其它产品中出现。

第二个产品：iKnow英语，与相同志趣的同学一起学英语，享受学习英语的乐趣

产品Logo：

最初的Android第一版：

第二版：

6月20号版本：

iPhone版本也是我们从0开始学习开发、申请App Store的帐号、提交审核到发布：

Android客户端和iPhone客户端近期都会有新版本更新，下一个大的版本特色将是围绕着“如何与相同志趣的同学一起学习交流”这个点来展开，LBS会作为其中一个途径。

等忙完这一阵子写一些更详细的分享文章。

如果你有Android手机的话请点击这个链接：https://market.android.com/details?id=com.iknow，在官方的电子市场、N多市场、应用汇、安卓市场等上搜索关键字”iKnow“也可以找到。

有iPhone的话，请点击这个链接：http://itunes.apple.com/cn/app/id443923760?mt=8，在市场上搜索”iKnow“也可以找到。

来体验一下吧。

我们一直致力于做一个有用、好用，能够给你带来帮助的产品，所以朋友们有任何想法什么的都可以跟我们提，可以在应用商店后面回复您的建议或者通过以下方式：

网站：www.imiknow.com

QQ群：138 787 125

微薄：http://weibo.com/1845827193

其它产品

最近提交App Store审核的应用包括”DotA视频“、”宠物视频“等，晚些跟朋友们分享。

最后

感谢我的女朋友（一直没有抱怨的支持我，一直忍受我的坏脾气），感谢我的弟弟，感谢我的父母，感谢一直支持我们的朋友们。

本文链接

Windows Phone 7 Series Developer General FAQ

2011-03-02T13:09:00Z

今天查找WP7对TCP/UDP的支持时顺手把其它FAQ也转过来方便查找，原文：Windows Phone 7 Series Developer General FAQ (Updated 5/19/2010)

Getting Started

First, get the tools:
• For Windows Phone Developer Tools CTP, you can download the complete (and free) toolset from here .
• If you wish to use Expression Blend 4, visit this page for download links and details. (Note if you already have the Windows Phone Developer Tools installed, you only need items 1, 3, and 4.)

Learn about the technologies:
• Silverlight: Visit The Official Microsoft Silverlight Site for samples, tutorials, and general information about learning Silverlight.
• XNA: Visit the XNA Creators Club Online for information about XNA. Also check out the XNA Creators Club Forums .

Get Samples and Libraries and play!
• The Forum's live list of samples for Windows Phone 7 (new!)
• Code Samples for Windows Phone
• Windows Phone 7 Series Development Training Kit
• OData client Library for Windows Phone 7 Series

Tools Issues

My installation failed
Before posting the issue in the forum, please check the event logs on your system for any errors that may provide clues.

My installation completed, but I am unable to start Visual Studio 2010 Express for Windows Phone. What should I do?
A common problem appears to be related to the user privileges during and after installation. To work around these issues, make sure you are logged in as Administrator, both during installation and when using the tools. Here is an installation checklist:
1. Check the Release Notes. Make sure your system and already-installed software have the prerequisite requirements, and that issue(s) you may be encountering are not already addressed there. (http://download.microsoft.com/download/D/9/2/D926FB38-BB43-4D87-AE5A-1A3391279FAC/ReleaseNotes.htm )
2. The CTP release does not currently support running from within a virtual machine.
3. Ensure that you are logged in as Administrator before launching the installer. Otherwise you may encounter registry or file permission issues during installation or when using the tools.
4. After installation completes, reboot the system. This clears up miscellaneous problems for some users.
5. Log in as Administrator before launching Visual Studio.

I am getting the error "The application cannot start"
Please see this blog note: http://blogs.msdn.com/visualstudio/archive/2009/10/29/how-to-fix-the-application-cannot-start-error.aspx

Deploying to the emulator is failing
If deploying to the emulator is failing with an error like "Connection failed because of invalid command-line arguments", try the following workarounds in the order indicated:
1. If you have just installed the Tools but have not rebooted yet, try rebooting first to see if that fixes the problem.
2. Try setting VS2010 to launch as Administrator. Here is the procedure. Make sure you are logged in as Administrator. Right click on Microsoft Visual Studio 2010 Express for Windows Phone, choose Properties, click on the Compatibility tab and turn on the check box for "Run this program as an Administrator". Make sure you are logged in as Administrator and then re-launch Visual Studio.
3. If the above does not work, close the solution and then delete the solution .suo file and/or the project .user file. Reopen and see if the deployment works.

The emulator seems slow
1. Use a computer that has “hardware virtualization technology” indicated in its BIOS setup screen (this is the technology used to enable Virtual PC etc.). And then you must ensure that the feature is turned on in the BIOS.
2. As indicated in the Release Notes, use a high performance DirectX 10 capable card with a WDDM 1.1 driver that can take advantage of GPU acceleration on Windows Phone Emulator. Ensure that you are using the very latest driver from the video card manufacturer.

Application Process in Foreground / Background

Can my app run in the background / circumvent the foreground requirement?
No, the application model in Windows Phone 7 Series is foreground only execution. If any other application (3rd party or built-in) is started while your application is running, you will get an event notifying you that your application is about to be terminated.

What happens when my application loses the foreground?
Your application will receive a notification that it is being closed. The time allotted your application after the foreground is lost has not yet been determined. If state persistence is desired, you will need to include the logic in your application to handle this.

What happens when my application is brought back after losing the foreground?
Your application will be started from the initial entry point. If state persistence is required, your application should have logic to determine if a state was previously saved and work to restore that state.

Does this means it is impossible to write apps that require background updates to be effective?
No! We have provided a Push Notification service that your application can utilize. Concepts such as Chat Programs, Turn-Based games, and other types of applications that rely on external events are perfect candidates for using Push Notifications. You can read more information about Push Notifications from MSDN: http://msdn.microsoft.com/en-us/library/ff402558%28VS.92%29.aspx

Can I use Push Notifications to start my application if it is not running?
Not directly: A cloud service can send a push notification to a device to update your application's tile, or to display a toast notification. The application will launch only if the user clicks either the tile or the toast notification.

Can I set a timer that will start my application?
No, the decision to start your application is solely up to the user.

Can my application be started based on system events?
This is unlikely, but this is still an open question. Most likely, you will be unable to start your application due to a system event, but you may be able to get a notification cached for when the user starts your application. More information on this will be posted as we learn more about it.

Can I write a Service DLL that can stay resident in the OS if I don't have a UI?
No, you will not be able to write service DLL's. All assemblies will run in their own sandbox, apart from the OS and each other.

Application Installation

How do I install applications on my device?
Applications will automatically be installed when downloaded from Marketplace.

Can I manually install applications without using the Marketplace?
No, "side-loading" applications is not permitted. The only way to get released applications on your device is through Marketplace.

How can I test my application on a device if I can't install it?
As a registered developer with Marketplace, you will be able to register a number of devices that you can directly deploy your application to for testing. It is not necessary to publish your application to Marketplace just to test it.

My application is for my company / specific group of people only, how do I distribute the app only to them on Marketplace?
The Marketplace does not currently have the ability to provide locked-off areas for private applications. Other than a few key exceptions for Mobile Operators, there is no way to gate your application to a specific group of people or devices at this time.

Marketplace Questions (new!)

How do I register as a developer for Marketplace?
Visit this site and follow the directions to register as a developer for Windows Phone.

How much does it cost to register and what do I get with the subscription?
There is currently a $99 annual subscription. For details about this and many other common questions, please see The Windows Marketplace FAQ .

This price and site indicates development for Windows Phone 6.x; will my account work for Windows Phone 7 as well?
Details concerning how Windows Phone 7 development will be handled with existing subscriptions and future pricing have not yet been announced. This point will be updated once this information is announced.

Where can I get support for Marketplace?
For general Windows Marketplace for Mobile questions, please visit their forum . (Note that there are not many details available for Marketplace's role with Windows Phone 7 yet.)

Device Connectivity

Is ActiveSync still used to connect the device to the PC?
No, synchronization is automatic similar to the way the Zune HD connects to the PC.

How should I transfer information over the Internet?
Web technologies such as HTTPGET and WebServices are supported as methods of communicating on the Internet. You can also use Push Notifications for communication when your application is not running.

Can I use Sockets for peer to peer communication?
Windows Phone 7 Series currently does not expose the Socket classes. While the version of Silverlight on the phone follows closely the feature list for Silverlight 3 on the desktop, it is a subset of those features and will not contain all classes. (It also holds a superset of classes not available in Silverlight 3.)

How can I connect with another client in real-time?
Peer-to-peer communication is not supported with this initial release of Windows Phone 7 Series. We are always evaluating the needs of our developers and users though and it may be determined that this feature be added in the future.

Hub/Pivot/Tab and other missing controls in Silverlight

Where is that hub control I’ve seen in several demos?
The “Hub” and “Pivot” controls that were seen in several demos at MIX are a work in progress and are not part of the current set of tools.

When will they be available?
There is no set schedule for these controls however the product group is closely watching the developer community to understand the kinds of controls that would be most useful. If there is a control you would like to see that is currently missing, please post a comment in the forum!

Can I make my own?
You can absolutely make your own controls. Note that the Pivot / Hub control is a popular request, chances are good that this is something that will be provided at some point as part of the official tools.

Device Storage

What is "Isolated Storage"
Isolated Storage refers to the space in the device file system your application occupies. You are not permitted to make file system calls outside of this space (including other application spaces or OS space.) This provides your application with its own "safe" sandbox, and prevents other applications from inadvertently (or maliciously) affecting your application's space.

Is there a local database available on Windows Phone 7 Series devices?
No, for this initial release of Windows Phone 7 Series, there are no local database API’s available.

How should I store information for my application?
You can store information in your own store space. If you have need of a large database there are other options as well: Windows Phone 7 Series has support for WebServices, which enable you to easily access information that you store on the Internet. With a database that is accessible to a webservice, your application can get data in real time while connected to the Internet.

How should I handle disconnected scenarios?
Without a connection to the Internet, you will not be able to access cloud based services for data. In cases like this it is recommended that your application gracefully handle this in some way (be it to store a cache of data in a custom format on the device, or advise the user of the lack of connectivity.)

My application is intended to run in an off-line scenario, What do I do if I can’t access the cloud?
There are two options for this scenario:
• Build your own data storage scheme on the device to be stored within device memory
• Continue developing for Windows Phone 6.5 or previous versions, which continue to be supported and do support local databases.

Will there be support for local databases in the future?
There are no currently announced plans to add this functionality; however we are closely monitoring the needs of the developers and users to identify features that would benefit everyone.

Development Technologies

What technologies and tools can I use to program for Windows Phone 7 Series?
You can currently use the managed language C# using Silverlight and XNA based on Compact Framework.

Can I use Windows Forms?
No, Windows Forms are not supported in the version of Compact Framework included with Windows Phone 7 Series.

How do I upgrade my existing Windows Forms applications to Silverlight?
First, become familiar with Silverlight. (You can learn more about Silverlight at The Official Microsoft Silverlight Site .) This will help you properly convert the UI aspects of your application from Windows Forms to Silverlight. The next step is to convert your business logic. Most of this should work without change, however there are some major changes in class support that you may need to seriously consider such as socket support.

Can I write my application in C++?
No, only managed code written in C# is supported for developing on the Windows Phone 7 Series platform. Unmanaged code and other languages (including Managed C++) are not supported.

Can I write my application in VB?
Not at this time, however this is being strongly considered for a future release of the developer tools.

Can I P/Invoke into System API’s?
No, as an ISV there is no access to the system API’s using P/Invoke. Any application that attempts to use P/Invoke will be rejected from being published to the Marketplace.

Can I P/Invoke my own native DLL?
No, native code may not be run as any part of your application. P/Invokes are not permitted.

What are the main benefits of using Expression Blend or Expression Studio?
These are very effective productivity optimization tools, used to easily adjust the program’s appearance and elements ( Fit and Finish) such as gradients, shapes, vector paths using a very inuitive designer UI. You can run these tools at the same time as Visual Studio, against the same Project.

Silverlight, XNA, and Compact Framework

What version of Silverlight does the Phone use?
The version of Silverlight on the phone is a very close subset of Silverlight 3 on the desktop. There are some features available beyond Silverlight 3 that provide phone specific functionality, but many applications that work well in Silverlight 3 on the desktop should work well on the phone.

Can I use XNA library calls in Silverlight?
Silverlight and XNA share a common code base in the Compact Framework. If a call is not GUI based, in most cases it can be shared between Silverlight and XNA.

本文链接

我们的创业步伐

2011-01-20T12:00:00Z

2010年对我来说是个难忘的一年，在比亚迪时从深圳出差来到北京，然后又从北京回到深圳，从比亚迪离职之后收到了微软Vender职位的Offer，所以又回到北京。虽然从北京回南方时我就默默的下决定以后不来北京了，但是我仍然禁不住这次这么好的学习机会，所以我放弃了更稳定的、看上去更好的工作重新来到陌生的北京。我就这么南北折腾，寻找离梦想更近的路子。

在微软工作的那段时间我收获很多，我看到了更牛的技术专家，看到了更高的思想境界，之前觉得非常神秘的东西仿佛理所应当知道，之前觉得无解的难题仿佛轻而易举。认识到这个世界牛人满天飞，我要努力做到的仅仅是不要变成井底之蛙。怀着谦虚和开放的胸怀才能更快的提高。

所以那为什么不变得更开放？尽力提高自己，帮助更多的人，尽力让自己更有价值？所以这就是为什么我在微软最大的收获不是技术，而是生活态度、眼界发生的微妙变化的原因。

在微软的工作那些日子，我几乎把全部的时间放在工作上，查询和学习更多的资料，但是即使这样我仍然感觉时间不够用，这也导致了我分享的博客文章少了，但是我仍然想分享更多有价值的东西，但是我首先得提高自己，不是吗？此刻我更想分享创业的经历和感悟，我想这是第一篇。

2010年10月中旬我辞职了，很多朋友不解，按照我之前的计划我会努力成为一个微软优秀的部门经理。收拾东西离开大门的时候我站在希格玛大厦前，热泪盈眶，走进的那一天我充满敬畏，但是离开的那一天我充满了感激。（在这里还要特别的感谢马宁、肖翔等一直给予我帮助的朋友和老师，虽然不再一起共事了，他们仍然对我们的创业给予鼓励和帮助。）

这次创业最初遇到的是发起人少辉，几次见面之后发现他就是个非常平易近人，爱讲好玩、搞笑经历的家伙，特别爱帮助别人，跟他在一起你发现创业是件充满乐趣的事。他甚至放弃了享有终身员工的待遇来创业。之后不断的进来新的团队成员：纯明、孙链、抱抱、宇光、于伟、iToday开源项目认识的锦峰，以及入职时认识的在微软做设计的庭宇，还有之后加入的晨龙等等。我们具有相似的价值观，我们都热爱我们做的事，我们给我们的团队起了一个名字 – MCOS Team。我们甚至有一个小泰迪：

团队的其他成员跟我一样碰到这样的疑问：现在的生活挺好的，为什么要创业？

这让我想起小时候经常听的那首歌 - 《再也不能这样活》，这是对我有很多影响的一首歌，我们总很容易变得安于现状，但是回首往事发现我们其实可以做更多事情的。人后悔的往往是没有做过的事情。我们是这么想的。

其实我创业的最直接原因是我之前发起的开源项目 - iToday，从这个开发项目中我认识了很多志同道合的朋友，而且让自己和别人有所收获的感觉太棒了，但是iToday的发展出现了问题，这其实就是开发项目的弊端，因为没有商业模式来支持开源开发团队，项目进度一拖再拖，开发人员也得赚钱吃饭，这个问题在中国显得更是问题，我们不得不放一放这个项目了。

不管在来到北京之前在华南师范大学科技开发公司的一个部门中组建团队，还是进入现在的团队的最初原因，我都在尝试完成一个承诺：继续开源项目，分享更多有价值的东西。但是真的很坎坷。

但是我一定会做到的。

创业之初，我和少辉、纯明经常一起聚餐聊聊我们的创业梦想，如果我们赚钱了，我们一定要拿出来一部分做医疗和环境建设。等做的更好一点时，我要去旅游更多地方，我要开阔自己的眼界，纯明要有一个研究院好好研究技术。吃饭之余随便聊聊的、看似只是虚幻的东西一直藏在我们心中，在我们艰难的时候带给我们信念和动力。

我们做沟通，出于我们有这样的感受：智能手机为什么不能让沟通变得更智能？为什么还要1角1条的短信？我们一直探索如何建立一个基于真实SNS的沟通工具，如何将虚拟世界跟真实世界的关系变得统一，怎样将一些只能在虚拟世界才能享受到的服务在真实世界中实现。

我们会一直努力“让沟通变得更好。”

MCOS - Magic Cube Of Soul，心灵魔方。为什么我们会给我们的产品和Team起一个这样的名字？我们每个人在生活中都扮演不同的角色，可以是员工，可以是父亲，可以是朋友，可以是老师…能够像玩魔方一样扮演好这些角色我们就能拥有幸福的生活，有的时候魔方的一面离另一面看似是这么的近，可又是那么的远。

当然最重要的是踏踏实实走好现在的每一步。

朋友问我我能坚持多久，我跟朋友说不要怀疑我的毅力。全职创业已经三个多月了，我也体验了三个月的酸甜苦辣，我也知道更丰富的体会还在后面，但是此刻我更加坚定了我的决心。与最开始朦胧的idea相比，我们已经清晰了我们的路子，当然也更坚定了我们的决心。

这几天抽空余时间阅读了《观止-微软创建NT和未来的夺命狂奔》，卡特勒带领的Team花了5年时间来创建NT，换作其他Team又有几个能坚持下来？这样的路子本来不就是“结果总是那么美好而过程总是漫长而艰辛的”？

        卡特勒很满意。他又一次战胜了所有怀疑他的人，证明了一个团队可以把混乱变得有序，不管它那么难控制。过去的一年如此艰难。这个团队去除了三万多个臭虫，难以置信。尽管有如此多的具体困难，但是许多人都坚持下来了，对此卡特勒“觉得有些吃惊，因为他们承受的压力是非常大的。”现在都结束了——包括所有人。

         独自在办公室中，卡特勒在他的计算机面前坐下，开始写一封信：

         NT正式发布到工厂生产了！

         让我再说一遍——NT发布了！！！

         这是非常漫长而艰难的一次奋斗。你们都出色地完成了自己的工作。

         感谢所有的人，谢谢你们的贡献，特别是在最后的三个月中，我们想尽办法，每天铲除了200多个臭虫，而没有产生过严重的副作用。为了做到这一点，每个人都付出了无比的努力。

         我们达到或者超过了所有发布的标准！

         当他写完后，他把这封信发送到了把所有团队成员联系在一起的计算机网络上。一瞬间，他让这个团队的所有人都感动了。

那么你是否也在找这样的一个团队，一个可以安放自己梦想的地方？我们一直在寻找更多志同道合的移动互联网创业者，你不用担心因为创业而不能保证生活水平，我们会提供让你满意的薪资和股份期权。

欢迎博友一起讨论创业的话题。

QQ：3423 67 776

GMail/GTalk/MSN：wangkeweinuaa@gmail.com

本文链接

Android NDK r5 Native Activity

2011-01-15T15:03:00Z

Convenience for implementing an activity that will be implemented purely in native code. That is, a game (or game-like thing). There is no need to derive from this class; you can simply declare it in your manifest, and use the NDK APIs from there.

A typical manifest would look like:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
        package="com.example.native_activity"
        android:versionCode="1"
        android:versionName="1.0">

    <!-- This is the platform API where NativeActivity was introduced. -->
    <uses-sdk android:minSdkVersion="8" />

    <!-- This .apk has no Java code itself, so set hasCode to false. -->
    <application android:label="@string/app_name" android:hasCode="false">

        <!-- Our activity is the built-in NativeActivity framework class.
             This will take care of integrating with our NDK code. -->
        <activity android:name="android.app.NativeActivity"
                android:label="@string/app_name"
                android:configChanges="orientation|keyboardHidden">
            <!-- Tell NativeActivity the name of or .so -->
            <meta-data android:name="android.app.lib_name"
                    android:value="native-activity" />
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>

</manifest>

A very simple example of native code that is run by NativeActivity follows. This reads input events from the user and uses OpenGLES to draw into the native activity's window.

#include <jni.h>
#include <errno.h>

#include <EGL/egl.h>
#include <GLES/gl.h>

#include <android/sensor.h>
#include <android/log.h>
#include <android_native_app_glue.h>

#define LOGI(...) ((void)__android_log_print(ANDROID_LOG_INFO, "native-activity", __VA_ARGS__))
#define LOGW(...) ((void)__android_log_print(ANDROID_LOG_WARN, "native-activity", __VA_ARGS__))

/**
 * Our saved state data.
 */
struct saved_state {
    float angle;
    int32_t x;
    int32_t y;
};

/**
 * Shared state for our app.
 */
struct engine {
    struct android_app* app;

    ASensorManager* sensorManager;
    const ASensor* accelerometerSensor;
    ASensorEventQueue* sensorEventQueue;

    int animating;
    EGLDisplay display;
    EGLSurface surface;
    EGLContext context;
    int32_t width;
    int32_t height;
    struct saved_state state;
};

/**
 * Initialize an EGL context for the current display.
 */
static int engine_init_display(struct engine* engine) {
    // initialize OpenGL ES and EGL

    /*
     * Here specify the attributes of the desired configuration.
     * Below, we select an EGLConfig with at least 8 bits per color
     * component compatible with on-screen windows
     */
    const EGLint attribs[] = {
            EGL_SURFACE_TYPE, EGL_WINDOW_BIT,
            EGL_BLUE_SIZE, 8,
            EGL_GREEN_SIZE, 8,
            EGL_RED_SIZE, 8,
            EGL_NONE
    };
    EGLint w, h, dummy, format;
    EGLint numConfigs;
    EGLConfig config;
    EGLSurface surface;
    EGLContext context;

    EGLDisplay display = eglGetDisplay(EGL_DEFAULT_DISPLAY);

    eglInitialize(display, 0, 0);

    /* Here, the application chooses the configuration it desires. In this
     * sample, we have a very simplified selection process, where we pick
     * the first EGLConfig that matches our criteria */
    eglChooseConfig(display, attribs, &config, 1, &numConfigs);

    /* EGL_NATIVE_VISUAL_ID is an attribute of the EGLConfig that is
     * guaranteed to be accepted by ANativeWindow_setBuffersGeometry().
     * As soon as we picked a EGLConfig, we can safely reconfigure the
     * ANativeWindow buffers to match, using EGL_NATIVE_VISUAL_ID. */
    eglGetConfigAttrib(display, config, EGL_NATIVE_VISUAL_ID, &format);

    ANativeWindow_setBuffersGeometry(engine->app->window, 0, 0, format);

    surface = eglCreateWindowSurface(display, config, engine->app->window, NULL);
    context = eglCreateContext(display, config, NULL, NULL);

    if (eglMakeCurrent(display, surface, surface, context) == EGL_FALSE) {
        LOGW("Unable to eglMakeCurrent");
        return -1;
    }

    eglQuerySurface(display, surface, EGL_WIDTH, &w);
    eglQuerySurface(display, surface, EGL_HEIGHT, &h);

    engine->display = display;
    engine->context = context;
    engine->surface = surface;
    engine->width = w;
    engine->height = h;
    engine->state.angle = 0;

    // Initialize GL state.
    glHint(GL_PERSPECTIVE_CORRECTION_HINT, GL_FASTEST);
    glEnable(GL_CULL_FACE);
    glShadeModel(GL_SMOOTH);
    glDisable(GL_DEPTH_TEST);

    return 0;
}

/**
 * Just the current frame in the display.
 */
static void engine_draw_frame(struct engine* engine) {
    if (engine->display == NULL) {
        // No display.
        return;
    }

    // Just fill the screen with a color.
    glClearColor(((float)engine->state.x)/engine->width, engine->state.angle,
            ((float)engine->state.y)/engine->height, 1);
    glClear(GL_COLOR_BUFFER_BIT);

    eglSwapBuffers(engine->display, engine->surface);
}

/**
 * Tear down the EGL context currently associated with the display.
 */
static void engine_term_display(struct engine* engine) {
    if (engine->display != EGL_NO_DISPLAY) {
        eglMakeCurrent(engine->display, EGL_NO_SURFACE, EGL_NO_SURFACE, EGL_NO_CONTEXT);
        if (engine->context != EGL_NO_CONTEXT) {
            eglDestroyContext(engine->display, engine->context);
        }
        if (engine->surface != EGL_NO_SURFACE) {
            eglDestroySurface(engine->display, engine->surface);
        }
        eglTerminate(engine->display);
    }
    engine->animating = 0;
    engine->display = EGL_NO_DISPLAY;
    engine->context = EGL_NO_CONTEXT;
    engine->surface = EGL_NO_SURFACE;
}

/**
 * Process the next input event.
 */
static int32_t engine_handle_input(struct android_app* app, AInputEvent* event) {
    struct engine* engine = (struct engine*)app->userData;
    if (AInputEvent_getType(event) == AINPUT_EVENT_TYPE_MOTION) {
        engine->animating = 1;
        engine->state.x = AMotionEvent_getX(event, 0);
        engine->state.y = AMotionEvent_getY(event, 0);
        return 1;
    }
    return 0;
}

/**
 * Process the next main command.
 */
static void engine_handle_cmd(struct android_app* app, int32_t cmd) {
    struct engine* engine = (struct engine*)app->userData;
    switch (cmd) {
        case APP_CMD_SAVE_STATE:
            // The system has asked us to save our current state.  Do so.
            engine->app->savedState = malloc(sizeof(struct saved_state));
            *((struct saved_state*)engine->app->savedState) = engine->state;
            engine->app->savedStateSize = sizeof(struct saved_state);
            break;
        case APP_CMD_INIT_WINDOW:
            // The window is being shown, get it ready.
            if (engine->app->window != NULL) {
                engine_init_display(engine);
                engine_draw_frame(engine);
            }
            break;
        case APP_CMD_TERM_WINDOW:
            // The window is being hidden or closed, clean it up.
            engine_term_display(engine);
            break;
        case APP_CMD_GAINED_FOCUS:
            // When our app gains focus, we start monitoring the accelerometer.
            if (engine->accelerometerSensor != NULL) {
                ASensorEventQueue_enableSensor(engine->sensorEventQueue,
                        engine->accelerometerSensor);
                // We'd like to get 60 events per second (in us).
                ASensorEventQueue_setEventRate(engine->sensorEventQueue,
                        engine->accelerometerSensor, (1000L/60)*1000);
            }
            break;
        case APP_CMD_LOST_FOCUS:
            // When our app loses focus, we stop monitoring the accelerometer.
            // This is to avoid consuming battery while not being used.
            if (engine->accelerometerSensor != NULL) {
                ASensorEventQueue_disableSensor(engine->sensorEventQueue,
                        engine->accelerometerSensor);
            }
            // Also stop animating.
            engine->animating = 0;
            engine_draw_frame(engine);
            break;
    }
}

/**
 * This is the main entry point of a native application that is using
 * android_native_app_glue.  It runs in its own thread, with its own
 * event loop for receiving input events and doing other things.
 */
void android_main(struct android_app* state) {
    struct engine engine;

    // Make sure glue isn't stripped.
    app_dummy();

    memset(&engine, 0, sizeof(engine));
    state->userData = &engine;
    state->onAppCmd = engine_handle_cmd;
    state->onInputEvent = engine_handle_input;
    engine.app = state;

    // Prepare to monitor accelerometer
    engine.sensorManager = ASensorManager_getInstance();
    engine.accelerometerSensor = ASensorManager_getDefaultSensor(engine.sensorManager,
            ASENSOR_TYPE_ACCELEROMETER);
    engine.sensorEventQueue = ASensorManager_createEventQueue(engine.sensorManager,
            state->looper, LOOPER_ID_USER, NULL, NULL);

    if (state->savedState != NULL) {
        // We are starting with a previous saved state; restore from it.
        engine.state = *(struct saved_state*)state->savedState;
    }

    // loop waiting for stuff to do.

    while (1) {
        // Read all pending events.
        int ident;
        int events;
        struct android_poll_source* source;

        // If not animating, we will block forever waiting for events.
        // If animating, we loop until all events are read, then continue
        // to draw the next frame of animation.
        while ((ident=ALooper_pollAll(engine.animating ? 0 : -1, NULL, &events,
                (void**)&source)) >= 0) {

            // Process this event.
            if (source != NULL) {
                source->process(state, source);
            }

            // If a sensor has data, process it now.
            if (ident == LOOPER_ID_USER) {
                if (engine.accelerometerSensor != NULL) {
                    ASensorEvent event;
                    while (ASensorEventQueue_getEvents(engine.sensorEventQueue,
                            &event, 1) > 0) {
                        LOGI("accelerometer: x=%f y=%f z=%f",
                                event.acceleration.x, event.acceleration.y,
                                event.acceleration.z);
                    }
                }
            }

            // Check if we are exiting.
            if (state->destroyRequested != 0) {
                engine_term_display(&engine);
                return;
            }
        }

        if (engine.animating) {
            // Done with events; draw next animation frame.
            engine.state.angle += .01f;
            if (engine.state.angle > 1) {
                engine.state.angle = 0;
            }

            // Drawing is throttled to the screen update rate, so there
            // is no need to do timing here.
            engine_draw_frame(&engine);
        }
    }
}

本文链接

Build Android Source Code

2011-01-15T08:39:00Z

Setting up your machine

To build the Android source files, you will need to use Linux or Mac OS. Building under Windows is not currently supported.

Linux

The Android build is routinely tested on recent versions of Ubuntu (6.06 and later), but reports of successes or failures on other distributions are welcome.

Ubuntu Linux (32-bit x86)

To set up your Linux development environment, make sure you have the following:

Required Packages:
- Git 1.5.4 or newer and the GNU Privacy Guard.

JDK 5.0, update 12 or higher.Java 6 is not supported, because of incompatibilities with @Override.

flex, bison, gperf, libsdl-dev, libesd0-dev, libwxgtk2.6-dev (optional), build-essential, zip, curl.

$ sudo apt-get install git-core gnupg sun-java5-jdk flex bison gperf libsdl-dev libesd0-dev libwxgtk2.6-dev build-essential zip curl libncurses5-dev zlib1g-dev

You might also want Valgrind, a tool that will help you find memory leaks, stack corruption, array bounds overflows, etc.

$ sudo apt-get install valgrind

Intrepid ( 8.10) users may need a newer version of libreadline:

$ sudo apt-get install lib32readline5-dev

Ubuntu Linux (64-bit x86)

This has not been as well tested. Please send success or failure reports to android-porting@googlegroups.com .

The Android build requires a 32-bit build environment as well as some other tools:

Required Packages:
- Git, JDK, flex, and the other packages as listed above in the i386 instructions:
- JDK 5.0, update 12 or higher.Java 6 is not supported, because of incompatibilities with @Override.
- Pieces from the 32-bit cross-building environment
- X11 development

$ sudo apt-get install git-core gnupg flex bison gperf build-essential zip curl sun-java5-jdk zlib1g-dev gcc-multilib g++-multilib libc6-dev-i386 lib32ncurses5-dev ia32-libs x11proto-core-dev libx11-dev lib32readline5-dev lib32z-dev

Set the system to use the right version of java by default:
$ sudo update-java-alternatives -s java-1.5.0-sun

X11: Ubuntu doesn't have packages for the X11 libraries, but that can be worked around with the following command:
$ sudo ln -s /usr/lib32/libX11.so.6 /usr/lib32/libX11.so

Running Linux in a virtual machine

If you are running Linux in a virtual machine, you will need at least 1.5GB of RAM and 10GB or more of disk space in order to build the Android tree.

Other Linux

There's no reason why Android cannot be built on non-Ubuntu systems. Please send any success or failure reports to android-porting@googlegroups.com . In general you will need:

Python 2.4, which you can download from python.org.
JDK 5.0, update 12 or higher, which you can download from java.sun.com. Java 6 is not supported, because of incompatibilities with @Override.
Git 1.5.4 or newer. You can find it at http://git.or.cz/.

Anything missing from this list? Please let us know!

Mac OS

Requirements:

To build the Android files in a Mac OS environment, you need an Intel/x86 machine running MacOS 10.4 ("Tiger") or 10.5 ("Leopard"). At the moment MacOS 10.6 ("Snow Leopard") is not supported. The Android build system and tools do not support the obsolete PowerPC architecture.
Android must be built on a case-sensitive file system.
- We recommend that you build Android on a partition that has been formatted with the "Case-sensitive Journaled HFS+" file system:
  - A case-sensitive file system is required because the sources contain files that differ only in case.
  - Journaled systems are more robust. (This is optional, but recommended.)
  - HFS+ is required to successfully build Mac OS applications such as the Android Emulator for OS X.
- If you want to avoid partitioning/formatting your hard drive, you can use a case-sensitive disk image instead.
  - To create the image:
    - launch /Applications/Utilities/Disk Utility
    - select "New Image"
    - size: 8 GB (this will work, but you can choose more if you want to)
    - volume format: case sensitive, journaled
  - This will create a .dmg file which, once mounted, acts as a drive with the required formatting for Android development. For a disk image named "android.dmg" stored in your home directory, you can add the following to your ~/.bash_profile to mount the image when you execute "mountAndroid":
    # command to mount the android file image
    function mountAndroid { hdiutil attach ~/android.dmg -mountpoint /Volumes/android; }
    
    Once mounted, you'll do all your work in the "android" volume. You can eject it (unmount it) just like you would with an external drive.

To set up your Mac OS development environment, follow these steps:

Install the XCode version 2.4 or later from http://developer.apple.com. We recommend version 3.0 or newer.
Install MacPorts. To do this:
1. Download and run the installer from http://www.macports.org/install.php
2. Make sure that /opt/local/bin is in your path before /usr/bin by running
  $ echo $PATH
  
  If you don't see /opt/local/bin, edit $HOME/.bash_profile and add the line export PATH=/opt/local/bin:$PATH after any other PATH-related lines. To verify that your path is now correct, open a new terminal and run echo $PATH again.
Get the following packages from port:
$ POSIXLY_CORRECT=1 sudo port install gmake libsdl git-core gnupg
If using Mac OS 10.4, also install:
$ POSIXLY_CORRECT=1 sudo port install bison
Upgrade GNU make to 3.81 or later by running the following command. (Mac OS doesn't come with a recent enough version.)
$ sudo ln -s gmake /opt/local/bin/make
Set an appropriate per-process file descriptor limit. To do this, add the following lines to your .bash_profile file:
# set the number of open files to be 1024
$ ulimit -S -n 1024
Note that this may not be necessary; on some systems, the output of "ulimit -S" will show "unlimited". In this case, there is no need to set the limit to 1024.

Installing Repo

Repo is a tool that makes it easier to work with Git in the context of Android. For more information about Repo, see Using Repo and Git .

To install, initialize, and configure Repo, follow these steps:

Make sure you have a~/bindirectory in your home directory, and check to be sure that this bin directory is in your path:
$ cd ~
$ mkdir bin
$ echo $PATH
Download thereposcript and make sure it is executable:
$ curl http://android.git.kernel.org/repo >~/bin/repo
$ chmod a+x ~/bin/repo

Initializing a Repo client

Create an empty directory to hold your working files:
$ mkdir mydroid
$ cd mydroid
Run "repo init" to bring down the latest version of Repo with all its most recent bug fixes. You must specify a URL for the manifest:
$ repo init -u git://android.git.kernel.org/platform/manifest.git
- If you would like to check out a branch other than "master", specify it with -b, like:
  $ repo init -u git://android.git.kernel.org/platform/manifest.git -b cupcake
When prompted, configure Repo with your real name and email address. If you plan to submit code, use an email address that is associated with a Google account .

A successful initialization will end with a message such as
repo initialized in /mydroid
Your client directory should now contain a.repodirectory where files such as the manifest will be kept.
What will my name and email be used for?
To use the Gerrit code-review tool, you will need an email address that is connected with a registered Google account (which does not have to be a Gmail address). Make sure this is a live address at which you can receive messages . The real name that you provide here will show up in attributions for your code submissions.

What is a manifest file?

The Android source files are divided among a number of different repositories. A manifest file contains a mapping of where the files from these repositories will be placed within your working directory w hen you synchronize your files.

Getting the files

To pull down files to your working directory from the repositories as specified in the default manifest, run
$ repo sync

For more about "repo sync" and other Repo commands, see Using Repo and Git .
The Android source files will be located in your working directory under their project names.

Verifying Git Tags

Load the following public key into your GnuPG key database.The key is used to sign annotated tags that represent releases.
$ gpg --import
then paste the key(s) below, and press Control-D to end the input and process the keys. After importing the keys, you can verify any tag with
$ git tag -v tagname
key 9AB10E78: "The Android Open Source Projectinitial-contribution@android.com"

-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: GnuPG v1.4.2.2 (GNU/Linux)

mQGiBEnnWD4RBACt9/h4v9xnnGDou13y3dvOx6/t43LPPIxeJ8eX9WB+8LLuROSV 
lFhpHawsVAcFlmi7f7jdSRF+OvtZL9ShPKdLfwBJMNkU66/TZmPewS4m782ndtw7
8tR1cXb197Ob8kOfQB3A9yk2XZ4ei4ZC3i6wVdqHLRxABdncwu5hOF9KXwCgkxMD 
u4PVgChaAJzTYJ1EG+UYBIUEAJmfearb0qRAN7dEoff0FeXsEaUA6U90sEoVks0Z 
wNj96SA8BL+a1OoEUUfpMhiHyLuQSftxisJxTh+2QclzDviDyaTrkANjdYY7p2cq 
/HMdOY7LJlHaqtXmZxXjjtw5Uc2QG8UY8aziU3IE9nTjSwCXeJnuyvoizl9/I1S5
jU5SA/9WwIps4SC84ielIXiGWEqq6i6/sk4I9q1YemZF2XVVKnmI1F4iCMtNKsR4
MGSa1gA8s4iQbsKNWPgp7M3a51JCVCu6l/8zTpA+uUGapw4tWCp4o0dpIvDPBEa9
b/aF/ygcR8mh5hgUfpF9IpXdknOsbKCvM9lSSfRciETykZc4wrRCVGhlIEFuZHJv 
aWQgT3BlbiBTb3VyY2UgUHJvamVjdCA8aW5pdGlhbC1jb250cmlidXRpb25AYW5k 
cm9pZC5jb20+iGAEExECACAFAknnWD4CGwMGCwkIBwMCBBUCCAMEFgIDAQIeAQIX 
gAAKCRDorT+BmrEOeNr+AJ42Xy6tEW7r3KzrJxnRX8mij9z8tgCdFfQYiHpYngkI 
2t09Ed+9Bm4gmEO5Ag0ESedYRBAIAKVW1JcMBWvV/0Bo9WiByJ9WJ5swMN36/vAl 
QN4mWRhfzDOk/Rosdb0csAO/l8Kz0gKQPOfObtyYjvI8JMC3rmi+LIvSUT9806Up 
hisyEmmHv6U8gUb/xHLIanXGxwhYzjgeuAXVCsv+EvoPIHbY4L/KvP5x+oCJIDbk 
C2b1TvVk9PryzmE4BPIQL/NtgR1oLWm/uWR9zRUFtBnE411aMAN3qnAHBBMZzKMX 
LWBGWE0znfRrnczI5p49i2YZJAjyX1P2WzmScK49CV82dzLo71MnrF6fj+Udtb5+
OgTg7Cow+8PRaTkJEW5Y2JIZpnRUq0CYxAmHYX79EMKHDSThf/8AAwUIAJPWsB/M 
pK+KMs/s3r6nJrnYLTfdZhtmQXimpoDMJg1zxmL8UfNUKiQZ6esoAWtDgpqt7Y7s 
KZ8laHRARonte394hidZzM5nb6hQvpPjt2OlPRsyqVxw4c/KsjADtAuKW9/d8phb 
N8bTyOJo856qg4oOEzKG9eeF7oaZTYBy33BTL0408sEBxiMior6b8LrZrAhkqDjA 
vUXRwm/fFKgpsOysxC6xi553CxBUCH2omNV6Ka1LNMwzSp9ILz8jEGqmUtkBszwo 
G1S8fXgE0Lq3cdDM/GJ4QXP/p6LiwNF99faDMTV3+2SAOGvytOX6KjKVzKOSsfJQ 
hN0DlsIw8hqJc0WISQQYEQIACQUCSedYRAIbDAAKCRDorT+BmrEOeCUOAJ9qmR0l 
EXzeoxcdoafxqf6gZlJZlACgkWF7wi2YLW3Oa+jv2QSTlrx4KLM=
=Wi5D 
-----END PGP PUBLIC KEY BLOCK-----

Building the code

To build the files, run make from within your working directory:
$ cd ~/mydroid
$ source build/envsetup.sh
$ lunch
$ make

If your build fails, complaining about a missing "run-java-tool", try setting the ANDROID_JAVA_HOME env var to $JAVA_HOME before making. E.g.,

$ export ANDROID_JAVA_HOME=$JAVA_HOME

Using an IDE

Using Eclipse for Android platform development

Troubleshooting

ImportError: No module na med readline

Mac users getting this should install Python 2.5.2.

Linux users that installed Python from source, make sure the dependencies for libreadline are installed, and rebuild Python.

本文链接

Android Code Style Guidelines for Contributors

2011-01-15T08:01:00Z

The rules below are not guidelines or recommendations, but strict rules. Contributions to Android generally will not be accepted if they do not adhere to these rules.

Not all existing code follows these rules, but all new code is expected to.

Java Language Rules

We follow standard Java coding conventions. We add a few rules:

Exceptions: Never catch and ignore them without explanation.
Exceptions: do not catch generic Exception, except in library code at the root of the stack.
Finalizers: generally don't use them.
Imports: Fully qualify imports

Java Library Rules

There are conventions for using Android's Java libraries and tools. In some cases, the convention has changed in important ways and older code might use a deprecated pattern or library. When working with such code, it's okay to continue the existing style (see Consistency). When creating new components never use deprecated libraries.

Java Style Rules

Programs are much easier to maintain when all files have a consistent style. We follow the standard Java coding style, as defined by Sun in their Code Conventions for the Java Programming Language, with a few exceptions and additions. This style guide is comprehensive and detailed and is in common usage in the Java community.

In addition, we enforce the following style rules:

Comments/Javadoc: write it; use standard style
Short methods: don't write giant methods
Fields: should either be at the top of the file, or immediately before the methods that use them
Local variables: limit the scope
Imports: android; third party alphabetical; java(x)
Indentation: 4 spaces, no tabs.
Line length: 100 columns
Field names: Non-public, non-static fields start with m.
Braces: Opening braces don't go on their own line.
Annotations: Use the standard annotations.
Acronyms are words: Treat acronyms as words in names, yielding XmlHttpRequest, getUrl(), etc.
TODO style: "TODO: write this description"
Consistency: Look at what's around you!
Logging: Be careful with logging. It's expensive.

Javatests Style Rules

Naming test methods: testMethod_specificCase is ok

Java Language Rules

Exceptions: do not ignore

Sometimes it is tempting to write code that completely ignores an exception like this:

void setServerPort(String value) {
    try {
        serverPort = Integer.parseInt(value);
    } catch (NumberFormatException e) { }
}

You must never do this. While you may think that your code will never encounter this error condition or that it is not important to handle it, ignoring exceptions like above creates mines in your code for someone else to trip over some day. You must handle every Exception in your code in some principled way. The specific handling varies depending on the case.

Anytime somebody has an empty catch clause they should have a creepy feeling. There are definitely times when it is actually the correct thing to do, but at least you have to think about it. In Java you can't escape the creepy feeling. -James Gosling

Acceptable alternatives (in order of preference) are:

Throw the exception up to the caller of your method.

void setServerPort(String value) throws NumberFormatException {
    serverPort = Integer.parseInt(value);
}

Throw a new exception that's appropriate to your level of abstraction.

void setServerPort(String value) throws ConfigurationException {
    try {
        serverPort = Integer.parseInt(value);
    } catch (NumberFormatException e) {
        throw new ConfigurationException("Port " + value + " is not valid.");
    }
}

Handle the error gracefully and substitute an appropriate value in the catch {} block.

/** Set port. If value is not a valid number, 80 is substituted. */
void setServerPort(String value) {
    try {
        serverPort = Integer.parseInt(value);
    } catch (NumberFormatException e) {
        serverPort = 80;  // default port for server 
    }
}

Catch the Exception and throw a new RuntimeException. This is dangerous: only do it if you are positive that if this error occurs, the appropriate thing to do is crash.
```
/** Set port. If value is not a valid number, die. */
void setServerPort(String value) {
    try {
        serverPort = Integer.parseInt(value);
    } catch (NumberFormatException e) {
        throw new RuntimeException("port " + value " is invalid, ", e);
    }
}
```
Note that the original exception is passed to the constructor for RuntimeException. If your code must compile under Java 1.3, you will need to omit the exception that is the cause.

Last resort: if you are confident that actually ignoring the exception is appropriate then you may ignore it, but you must also comment why with a good reason:

/** If value is not a valid number, original port number is used. */
void setServerPort(String value) {
    try {
        serverPort = Integer.parseInt(value);
    } catch (NumberFormatException e) {
        // Method is documented to just ignore invalid user input.
        // serverPort will just be unchanged.
    }
}

Exceptions: do not catch generic Exception

Sometimes it is tempting to be lazy when catching exceptions and do something like this:

try {
    someComplicatedIOFunction();        // may throw IOException 
    someComplicatedParsingFunction();   // may throw ParsingException 
    someComplicatedSecurityFunction();  // may throw SecurityException 
    // phew, made it all the way 
} catch (Exception e) {               // I'll just catch all exceptions 
    handleError();                      // with one generic handler!
}

You should not do this. In almost all cases it is inappropriate to catch generic Exception or Throwable, preferably not Throwable, because it includes Error exceptions as well. It is very dangerous. It means that Exceptions you never expected (including RuntimeExceptions like ClassCastException) end up getting caught in application-level error handling. It obscures the failure handling properties of your code. It means if someone adds a new type of Exception in the code you're calling, the compiler won't help you realize you need to handle that error differently. And in most cases you shouldn't be handling different types of exception the same way, anyway.

There are rare exceptions to this rule: certain test code and top-level code where you want to catch all kinds of errors (to prevent them from showing up in a UI, or to keep a batch job running). In that case you may catch generic Exception (or Throwable) and handle the error appropriately. You should think very carefully before doing this, though, and put in comments explaining why it is safe in this place.

Alternatives to catching generic Exception:

Catch each exception separately as separate catch blocks after a single try. This can be awkward but is still preferable to catching all Exceptions. Beware repeating too much code in the catch blocks.
Refactor your code to have more fine-grained error handling, with multiple try blocks. Split up the IO from the parsing, handle errors separately in each case.
Rethrow the exception. Many times you don't need to catch the exception at this level anyway, just let the method throw it.

Remember: exceptions are your friend! When the compiler complains you're not catching an exception, don't scowl. Smile: the compiler just made it easier for you to catch runtime problems in your code.

Finalizers

What it is: Finalizers are a way to have a chunk of code executed when an object is garbage collected.

Pros: can be handy for doing cleanup, particularly of external resources.

Cons: there are no guarantees as to when a finalizer will be called, or even that it will be called at all.

Decision: we don't use finalizers. In most cases, you can do what you need from a finalizer with good exception handling. If you absolutely need it, define a close() method (or the like) and document exactly when that method needs to be called. See InputStream for an example. In this case it is appropriate but not required to print a short log message from the finalizer, as long as it is not expected to flood the logs.

Imports

Wildcards in imports

What it is: When you want to use class Bar from package foo,there are two possible ways to import it:

import foo.*;
import foo.Bar;

Pros of #1: Potentially reduces the number of import statements.

Pros of #2: Makes it obvious what classes are actually used. Makes code more readable for maintainers.

Decision: Use style #2 for importing all Android code. An explicit exception is made for java standard libraries (java.util.*, java.io.*, etc.) and unit test code (junit.framework.*).

Comments/Javadoc

Every file should have a copyright statement at the top. Then a package statement and import statements should follow, each block separated by a blank line. And then there is the class or interface declaration. In the Javadoc comments, describe what the class or interface does.

/*
 * Copyright (C) 2010 The Android Open Source Project 
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at 
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software 
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and 
 * limitations under the License.
 */

package com.android.internal.foo;

import android.os.Blah;
import android.view.Yada;

import java.sql.ResultSet;
import java.sql.SQLException;

/**
 * Does X and Y and provides an abstraction for Z.
 */
public class Foo {
    ...
}

Every class and nontrivial public method you write must contain a Javadoc comment with at least one sentence describing what the class or method does. This sentence should start with a 3rd person descriptive verb. Examples:

/** Returns the correctly rounded positive square root of a double value. */
static double sqrt(double a) {
}

/**
 * Constructs a new String by converting the specified array of 
 * bytes using the platform's default character encoding.
 */
public String(byte[] bytes) {
}

You do not need to write Javadoc for trivial get and set methods such as setFoo() if all your Javadoc would say is "sets Foo". If the method does something more complex (such as enforcing a constraint or having an important side effect), then you must document it. And if it's not obvious what the property "Foo" means, you should document it.

Every method you write, whether public or otherwise, would benefit from Javadoc. Public methods are part of an API and therefore require Javadoc.

Android does not currently enforce a specific style for writing Javadoc comments, but you should follow the Sun Javadoc conventions.

Short methods

To the extent that it is feasible, methods should be kept small and focused. It is, however, recognized that long methods are sometimes appropriate, so no hard limit is placed on method length. If a method exceeds 40 lines or so, think about whether it can be broken up without harming the structure of the program.

Local variables

The scope of local variables should be kept to a minimum (Effective Java Item 29). By doing so, you increase the readability and maintainability of your code and reduce the likelihood of error. Each variable should be declared in the innermost block that encloses all uses of the variable.

Local variables should be declared at the point they are first used. Nearly every local variable declaration should contain an initializer. If you don't yet have enough information to initialize a variable sensibly, you should postpone the declaration until you do.

One exception to this rule concerns try-catch statements. If a variable is initialized with the return value of a method that throws a checked exception, it must be initialized inside a try block. If the value must be used outside of the try block, then it must be declared before the try block, where it cannot yet be sensibly initialized:

// Instantiate class cl, which represents some sort of Set 
Set s = null;
try {
    s = (Set) cl.newInstance();
} catch(IllegalAccessException e) {
    throw new IllegalArgumentException(cl + " not accessible");
} catch(InstantiationException e) {
    throw new IllegalArgumentException(cl + " not instantiable");
}

// Exercise the set 
s.addAll(Arrays.asList(args));

But even this case can be avoided by encapsulating the try-catch block in a method:

Set createSet(Class cl) {
    // Instantiate class cl, which represents some sort of Set 
    try {
        return (Set) cl.newInstance();
    } catch(IllegalAccessException e) {
        throw new IllegalArgumentException(cl + " not accessible");
    } catch(InstantiationException e) {
        throw new IllegalArgumentException(cl + " not instantiable");
    }
}

...

// Exercise the set 
Set s = createSet(cl);
s.addAll(Arrays.asList(args));

Loop variables should be declared in the for statement itself unless there is a compelling reason to do otherwise:

for (int i = 0; i n; i++) {
    doSomething(i);
}

for (Iterator i = c.iterator(); i.hasNext(); ) {
    doSomethingElse(i.next());
}

Imports

The ordering of import statements is:

Android imports
Imports from third parties (com, junit, net, org)
java and javax

To exactly match the IDE settings, the imports should be:

Alphabetical within each grouping.
Capital letters are considered to come before lower case letter (e.g. Z before a).
There should be a blank line between each major grouping (android, com, junit, net, org, java, javax).

Why?

Originally there was no style requirement on the ordering. This meant that the IDE's were either always changing the ordering, or IDE developers had to disable the automatic import management features and maintain the imports by hand. This was deemed bad. When java-style was asked, the preferred styles were all over the map. It pretty much came down to our needing to "pick an ordering and be consistent." So we chose a style, updated the style guide, and made the IDEs obey it. We expect that as IDE users work on the code, the imports in all of the packages will end up matching this pattern without any extra engineering effort.

The style chosen such that:

The imports people want to look at first tend to be at the top (android)
The imports people want to look at least tend to be at the bottom (java)
Humans can easily follow the style
The IDE's can follow the style

What about static imports?

The use and location of static imports have been mildly controversial issues. Some people would prefer static imports to be interspersed with the remaining imports, some would prefer them reside above or below all other imports. Additinally, we have not yet come up with a way to make all IDEs use the same ordering.

Since most people consider this a low priority issue, just use your judgement and please be consistent.

Indentation

We use 4 space indents for blocks. We never use tabs. When in doubt, be consistent with code around you.

We use 8 space indents for line wraps, including function calls and assignments. For example, this is correct:

Instrument i =
        someLongExpression(that, wouldNotFit, on, one, line);

and this is not correct:

Instrument i =
    someLongExpression(that, wouldNotFit, on, one, line);

Field Names

Non-public, non-static field names start with m.
Static field names start with s.
Other fields start with a lower case letter.
Public static final fields (constants) are ALL_CAPS_WITH_UNDERSCORES.

For example:

public class MyClass {
    public static final int SOME_CONSTANT = 42;
    public int publicField;
    private static MyClass sSingleton;
    int mPackagePrivate;
    private int mPrivate;
    protected int mProtected;
}

Braces

Braces do not go on their own line; they go on the same line as the code before them. So:

class MyClass {
    int func() {
        if (something) {
            // ...
        } else if (somethingElse) {
            // ...
        } else {
            // ...
        }
    }
}

We require braces around the statements for a conditional. Except, if the entire conditional (the condition and the body) fit on one line, you may (but are not obligated to) put it all on one line. That is, this is legal:

if (condition) {
    body(); // ok 
}
if (condition) body(); // ok

but this is still illegal:

if (condition)
    body(); // bad

Line length

Each line of text in your code should be at most 100 characters long.

There has been lots of discussion about this rule and the decision remains that 100 characters is the maximum.

Exception: if a comment line contains an example command or a literal URL longer than 100 characters, that line may be longer than 100 characters for ease of cut and paste.

Exception: import lines can go over the limit because humans rarely see them. This also simplifies tool writing.

Java 1.5 Annotations

Annotations should precede other modifiers for the same language element. Simple marker annotations (e.g. @Override) can be listed on the same line with the language element. If there are multiple annotations, or parameterized annotations, they should each be listed one-per-line in alphabetical order.

Android -standard practices for the three predefined annotations in Java 1.5's are:

@Deprecated

The @Deprecated annotation must be used whenever the use of the annotated element is discouraged. If you use the @Deprecated annotation, you must also have a @deprecated Javadoc tag and it should name an alternate implementation. In addition, remember that a @Deprecated method is still supposed to work.

If you see old code that has a @deprecated Javadoc tag, please add the @Deprecated annotation.

@Override

The @Override annotation must be used whenever a method overrides the declaration or implementation from a super-class.

For example, if you use the @inheritdocs Javadoc tag, and derive from a class (not an interface), you must also annotate that the method @Overrides the parent class's method.

@SuppressWarnings

The @SuppressWarnings annotation should only be used under circumstances where it is impossible to eliminate a warning. If a warning passes this "impossible to eliminate" test, the @SuppressWarnings annotation must be used, so as to ensure that all warnings reflect actual problems in the code.

When a @SuppressWarnings annotation is necessary, it must be prefixed with a TODO comment that explains the "impossible to eliminate" condition. This will normally identify an offending class that has an awkward interface. For example:

// TODO: The third-party class com.third.useful.Utility.rotate() needs generics 
@SuppressWarnings("generic-cast")
List<String> blix = Utility.rotate(blax);

When a @SuppressWarnings annotation is required, the code should be refactored to isolate the software elements where the annotation applies.

Acronyms in names

Treat acronyms and abbreviations as words. The names are much more readable:

Good
Bad

XmlHttpRequest
XMLHTTPRequest

getCustomerId
getCustomerID

This style rule also applies when an acronym or abbreviation is the entire name:

Good
Bad

class Html
class HTML

String url;
String URL;

long id;
long ID;

Both the JDK and the Android code bases are very inconsistent with regards to acronyms, therefore, it is virtually impossible to be consistent with the code around you. Bite the bullet, and treat acronyms as words.

For further justifications of this style rule, see Effective Java Item 38 and Java Puzzlers Number 68.

TODO style

Use TODO comments for code that is temporary, a short-term solution, or good-enough but not perfect.

TODOs should include the string TODO in all caps, followed by a colon:

// TODO: Remove this code after the UrlTable2 has been checked in.

// TODO: Change this to use a flag instead of a constant.

If your TODO is of the form "At a future date do something" make sure that you either include a very specific date ("Fix by November 2005") or a very specific event ("Remove this code after all production mixers understand protocol V7.").

Consistency

Our parting thought: BE CONSISTENT. If you're editing code, take a few minutes to look at the code around you and determine its style. If they use spaces around their if clauses, you should too. If their comments have little boxes of stars around them, make your comments have little boxes of stars around them too.

The point of having style guidelines is to have a common vocabulary of coding, so people can concentrate on what you're saying, rather than on how you're saying it. We present global style rules here so people know the vocabulary. But local style is also important. If code you add to a a file looks drastically different from the existing code around it, it throws readers out of their rhythm when they go to read it. Try to avoid this.

Logging

While logging is necessary it has a significantly negative impact on performance and quickly loses its usefulness if it's not kept reasonably terse. The logging facilities provides five different levels of logging. Below are the different levels and when and how they should be used.

ERROR: This level of logging should be used when something fatal has happened, i.e. something that will have user-visible consequences and won't be recoverable without explicitly deleting some data, uninstalling applications, wiping the data partitions or reflashing the entire phone (or worse). This level is always logged. Issues that justify some logging at the ERROR level are typically good candidates to be reported to a statistics-gathering server.
WARNING: This level of logging should used when something serious and unexpected happened, i.e. something that will have user-visible consequences but is likely to be recoverable without data loss by performing some explicit action, ranging from waiting or restarting an app all the way to re-downloading a new version of an application or rebooting the device. This level is always logged. Issues that justify some logging at the WARNING level might also be considered for reporting to a statistics-gathering server.
INFORMATIVE: This level of logging should used be to note that something interesting to most people happened, i.e. when a situation is detected that is likely to have widespread impact, though isn't necessarily an error. Such a condition should only be logged by a module that reasonably believes that it is the most authoritative in that domain (to avoid duplicate logging by non-authoritative components). This level is always logged.
DEBUG: This level of logging should be used to further note what is happening on the device that could be relevant to investigate and debug unexpected behaviors. You should log only what is needed to gather enough information about what is going on about your component. If your debug logs are dominating the log then you probably should be using verbose logging. This level will be logged, even on release builds, and is required to be surrounded by an if (LOCAL_LOG) or if (LOCAL_LOGD) block, where LOCAL_LOG[D] is defined in your class or subcomponent, so that there can exist a possibility to disable all such logging. There must therefore be no active logic in an if (LOCAL_LOG) block. All the string building for the log also needs to be placed inside the if (LOCAL_LOG) block. The logging call should not be re-factored out into a method call if it is going to cause the string building to take place outside of the if (LOCAL_LOG) block. There is some code that still says if (localLOGV). This is considered acceptable as well, although the name is nonstandard.
VERBOSE: This level of logging should be used for everything else. This level will only be logged on debug builds and should be surrounded by if (LOCAL_LOGV) block (or equivalent) so that it can be compiled out by default. Any string building will be stripped out of release builds and needs to appear inside the if (LOCAL_LOGV) block.

Note: Within a given module, other than at the VERBOSE level, an error should only be reported once if possible: within a single chain of function calls within a module, only the innermost function should return the error, and callers in the same module should only add some logging if that significantly helps to isolate the issue.

Note: In a chain of modules, other than at the VERBOSE level, when a lower-level module detects invalid data coming from a higher-level module, the lower-level module should only log this situation to the DEBUG log, and only if logging provides information that is not otherwise available to the caller. Specifically, there is no need to log situations where an exception is thrown (the exception should contain all the relevant information), or where the only information being logged is contained in an error code. This is especially important in the interaction between the framework and applications, and conditions caused by third-party applications that are properly handled by the framework should not trigger logging higher than the DEBUG level. The only situations that should trigger logging at the INFORMATIVE level or higher is when a module or application detects an error at its own level or coming from a lower level.

Note: When a condition that would normally justify some logging is likely to occur many times, it can be a good idea to implement some rate-limiting mechanism to prevent overflowing the logs with many duplicate copies of the same (or very similar) information.

Note: Losses of network connectivity are considered common and fully expected and should not be logged gratuitously. A loss of network connectivity that has consequences within an app should be logged at the DEBUG or VERBOSE level (depending on whether the consequences are serious enough and unexpected enough to be logged in a release build).

Note: A full filesystem on a filesystem that is acceessible to or on behalf of third-party applications should not be logged at a level higher than INFORMATIVE.

Note: Invalid data coming from any untrusted source (including any file on shared storage, or data coming through just about any network connections) is considered expected and should not trigger any logging at a level higher then DEBUG when it's detected to be invalid (and even then logging should be as limited as possible).

Note: Keep in mind that the '+' operator, when used on Strings, implicitly creates a StringBuilder with the default buffer size (16 characters) and potentially quite a few other temporary String objects, i.e. that explicitly creating StringBuilders isn't more expensive than relying on the default '+' operator (and can be a lot more efficient in fact). Also keep in mind that code that calls Log.v() is compiled and executed on release builds, including building the strings, even if the logs aren't being read.

Note: Any logging that is meant to be read by other people and to be available in release builds should be terse without being cryptic, and should be reasonably understandable. This includes all logging up to the DEBUG level.

Note: When possible, logging should be kept on a single line if it makes sense. Line lengths up to 80 or 100 characters are perfectly acceptable, while lengths longer than about 130 or 160 characters (including the length of the tag) should be avoided if possible.

Note: Logging that reports successes should never be used at levels higher than VERBOSE.

Note: Temporary logging that is used to diagnose an issue that's hard to reproduce should be kept at the DEBUG or VERBOSE level, and should be enclosed by if blocks that allow to disable it entirely at compile-time.

Note: Be careful about security leaks through the log. Private information should be avoided. Information about protected content must definitely be avoided. This is especially important when writing framework code as it's not easy to know in advance what will and will not be private information or protected content.

Note: System.out.println() (or printf() for native code) should never be used. System.out and System.err get redirected to /dev/null, so your print statements will have no visible effects. However, all the string building that happens for these calls still gets executed.

Note: The golden rule of logging is that your logs may not unnecessarily push other logs out of the buffer, just as others may not push out yours.

Javatests Style Rules

Naming test methods

When naming test methods, you can use an underscore to seperate what is being tested from the specific case being tested. This style makes it easier to see exactly what cases are being tested.

For example:

testMethod_specificCase1 testMethod_specificCase2void testIsDistinguishable_protanopia() {
    ColorMatcher colorMatcher = new ColorMatcher(PROTANOPIA)
    assertFalse(colorMatcher.isDistinguishable(Color.RED, Color.BLACK))
    assertTrue(colorMatcher.isDistinguishable(Color.X, Color.Y))
}

本文链接

基于 OAuth 安全协议的 Java 应用编程

2011-01-14T11:16:00Z

原文地址：http://www.ibm.com/developerworks/cn/java/j-lo-oauth/index.html

OAuth 简介

OAuth 是由 Blaine Cook、Chris Messina、Larry Halff 及 David Recordon 共同发起的，目的在于为 API 访问授权提供一个安全、开放的标准。

基于 OAuth 认证授权具有以下特点：

安全。OAuth 与别的授权方式不同之处在于：OAuth 的授权不会使消费方（Consumer）触及到用户的帐号信息（如用户名与密码），也是是说，消费方无需使用用户的用户名与密码就可以申请获得该用户资源的授权。
开放。任何消费方都可以使用 OAuth 认证服务，任何服务提供方 (Service Provider) 都可以实现自身的 OAuth 认证服务。
简单。不管是消费方还是服务提供方，都很容易于理解与使用。

OAuth 的解决方案如下图所示。

图 1. OAuth Solution

如图 1 所示 OAuth 解决方案中用户、消费方及其服务提供方之间的三角关系：当用户需要 Consumer 为其提供某种服务时，该服务涉及到需要从服务提供方那里获取该用户的保护资源。OAuth 保证：只有在用户显式授权的情况下（步骤 4），消费方才可以获取该用户的资源，并用来服务于该用户。

从宏观层次来看，OAuth 按以下方式工作：

消费方与不同的服务提供方建立了关系。
消费方共享一个密码短语或者是公钥给服务提供方，服务提供方使用该公钥来确认消费方的身份。
消费方根据服务提供方将用户重定向到登录页面。
该用户登录后告诉服务提供方该消费方访问他的保护资源是没问题的。

OAuth 认证授权流程

在了解 OAuth 认证流程之前，我们先来了解一下 OAuth 协议的一些基本术语定义：

Consumer Key：消费方对于服务提供方的身份唯一标识。
Consumer Secret：用来确认消费方对于 Consumer Key 的拥有关系。
Request Token：获得用户授权的请求令牌，用于交换 Access Token。
Access Token：用于获得用户在服务提供方的受保护资源。
Token Secret：用来确认消费方对于令牌（Request Token 和 Access Token）的拥有关系。

图 2. OAuth 授权流程（摘自 OAuth 规范）

对于图 2 具体每一执行步骤，解释如下：

消费方向 OAuth 服务提供方请求未授权的 Request Token。
OAuth 服务提供方在验证了消费方的合法请求后，向其颁发未经用户授权的 Request Token 及其相对应的 Token Secret。
消费方使用得到的 Request Token，通过 URL 引导用户到服务提供方那里，这一步应该是浏览器的行为。接下来，用户可以通过输入在服务提供方的用户名 / 密码信息，授权该请求。一旦授权成功，转到下一步。
服务提供方通过 URL 引导用户重新回到消费方那里，这一步也是浏览器的行为。
在获得授权的 Request Token 后，消费方使用授权的 Request Token 从服务提供方那里换取 Access Token。
OAuth 服务提供方同意消费方的请求，并向其颁发 Access Token 及其对应的 Token Secret。
消费方使用上一步返回的 Access Token 访问用户授权的资源。

总的来讲，在 OAuth 的技术体系里，服务提供方需要提供如下基本的功能：

第 1、实现三个 Service endpoints，即：提供用于获取未授权的 Request Token 服务地址，获取用户授权的 Request Token 服务地址，以及使用授权的 Request Token 换取 Access Token 的服务地址。
第 2、提供基于 Form 的用户认证，以便于用户可以登录服务提供方做出授权。
第 3、授权的管理，比如用户可以在任何时候撤销已经做出的授权。

而对于消费方而言，需要如下的基本功能：

第 1、从服务提供方获取 Customer Key/Customer Secret。
第 2、提供与服务提供方之间基于 HTTP 的通信机制，以换取相关的令牌。

我们具体来看一个使用 OAuth 认证的例子。

在传统的网站应用中，如果您想在网站 A 导入网站 B 的联系人列表，需要在网站 A 输入您网站 B 的用户名、密码信息。例如，您登陆 Plaxo (https://www.plaxo.com )，一个联系人管理网站，当您想把 GMail 的联系人列表导入到 Plaxo，您需要输入您的 GMail 用户名 / 密码，如图 3 所示：

图 3. 在 Plaxo 获得 GMail 联系人

在这里，Plaxo 承诺不会保存您在 Gmail 的密码。

如果使用 OAuth 认证，情况是不同的，您不需要向网站 A（扮演 Consumer 角色）暴露您网站 B（扮演 Service Provider 角色）的用户名、密码信息。例如，您登录 http://lab.madgex.com/oauth-net/googlecontacts/default.aspx 网站，如图 4 所示：

图 4. 在 lab.madgex.com 获得 GMail 联系人

点击“Get my Google Contacts”，浏览器将会重定向到 Google，引导您登录 Google，如图 5 所示：

图 5. 登录 Google

登录成功后，将会看到图 6 的信息：

图 6. Google 对 lab.madgex.com 网站授权

在您登录 Google，点击“Grant access”，授权 lab.madgex.com 后，lab.madgex.com 就能获得您在 Google 的联系人列表。

在上面的的例子中，网站 lab.madgex.com 扮演着 Consumer 的角色，而 Google 是 Service Provider，lab.madgex.com 使用基于 OAuth 的认证方式从 Google 获得联系人列表。

下一节，本文会给出一个消费方实现的例子，通过 OAuth 机制请求 Google Service Provider 的 OAuth Access Token，并使用该 Access Token 访问用户的在 Google 上的日历信息 (Calendar)。

示例

准备工作

作为消费方，首先需要访问 https://www.google.com/accounts/ManageDomains，从 Google 那里获得标志我们身份的 Customer Key 及其 Customer Secret。另外，您可以生成自己的自签名 X509 数字证书，并且把证书上传给 Google，Google 将会使用证书的公钥来验证任何来自您的请求。

具体的操作步骤，请读者参考 Google 的说明文档：http://code.google.com/apis/gdata/articles/oauth.html。

在您完成这些工作，您将会得到 OAuth Consumer Key 及其 OAuth Consumer Secret，用于我们下面的开发工作。

如何获得 OAuth Access Token

以下的代码是基于 Google Code 上提供的 OAuth Java 库进行开发的，读者可以从 http://oauth.googlecode.com/svn/code/java/core/ 下载获得。

指定 Request Token URL，User Authorization URL，以及 Access Token URL，构造 OAuthServiceProvider 对象：

OAuthServiceProvider serviceProvider = new OAuthServiceProvider( 
    "https://www.google.com/accounts/OAuthGetRequestToken", 
    "https://www.google.com/accounts/OAuthAuthorizeToken", 
    "https://www.google.com/accounts/OAuthGetAccessToken");

指定 Customer Key，Customer Secret 以及 OAuthServiceProvider，构造 OAuthConsumer 对象：

OAuthConsumer oauthConsumer = new OAuthConsumer(null 
    , "www.example.com" 
    , "hIsGkM+T4+90fKNesTtJq8Gs"
    , serviceProvider);

为 OAuthConsumer 指定签名方法，以及提供您自签名 X509 数字证书的 private key。

oauthConsumer.setProperty(OAuth.OAUTH_SIGNATURE_METHOD, OAuth.RSA_SHA1);
oauthConsumer.setProperty(RSA_SHA1.PRIVATE_KEY, privateKey);

由 OAuthConsumer 对象生成相应的 OAuthAccessor 对象：
```
accessor = new OAuthAccessor(consumer); 
```

指定您想要访问的 Google 服务，在这里我们使用的是 Calendar 服务：

Collection<? extends Map.Entry> parameters 
    = OAuth.newList("scope","http://www.google.com/calendar/feeds/");

通过 OAuthClient 获得 Request Token:
```
OAuthMessage response = getOAuthClient().getRequestTokenResponse( 
    accessor, null, parameters); 
```
使用 Request Token, 将用户重定向到授权页面，如图 7 所示：

图 7. OAuth User Authorization
当用户点击“Grant access”按钮，完成授权后，再次通过 OAuthClient 获得 Access Token：
```
oauthClient.getAccessToken(accessor, null, null); 
```

在上述步骤成功完成后，Access Token 将保存在 accessor 对象的 accessToken 成员变量里。查看您的 Google Account 安全管理页面，可以看到您授权的所有消费方，如图 8 所示。

图 8. Authorized OAuth Access to your Google Account

使用 OAuth Access Token 访问 Google 服务

接下来，我们使用上一节获得的 Access Token 设置 Google Service 的 OAuth 认证参数，然后从 Google Service 获取该用户的 Calendar 信息：

OAuthParameters para = new OAuthParameters(); 
para.setOAuthConsumerKey("www.example.com"); 
para.setOAuthToken(accessToken); 
googleService.setOAuthCredentials(para, signer);

清单 1 是完整的示例代码，供读者参考。

清单 1. 基于 OAuth 认证的 Google Service 消费方实现

import java.util.Collection; 
import java.util.Map; 
import net.oauth.OAuth; 
import net.oauth.OAuthAccessor; 
import net.oauth.OAuthConsumer; 
import net.oauth.client.OAuthClient; 

 public class DesktopClient { 
    private final OAuthAccessor accessor; 
    private OAuthClient oauthClient = null; 
    public DesktopClient(OAuthConsumer consumer) { 
        accessor = new OAuthAccessor(consumer); 
    } 

    public OAuthClient getOAuthClient() { 
        return oauthClient; 
    } 

    public void setOAuthClient(OAuthClient client) { 
        this.oauthClient = client; 
    } 

    //get the OAuth access token. 
    public String getAccessToken(String httpMethod, 	
	    Collection<? extends Map.Entry> parameters) throws Exception { 
        getOAuthClient().getRequestTokenResponse(accessor, null,parameters); 

        String authorizationURL = OAuth.addParameters( 
		    accessor.consumer.serviceProvider.userAuthorizationURL, 
			 OAuth.OAUTH_TOKEN, accessor.requestToken); 

        //Launch the browser and redirects user to authorization URL 
        Runtime.getRuntime().exec("rundll32 url.dll,FileProtocolHandler " 
		    + authorizationURL); 

        //wait for user's authorization 
        System.out.println("Please authorize your OAuth request token. " 
		    + "Once that is complete, press any key to continue..."); 
        System.in.read(); 
        oauthClient.getAccessToken(accessor, null, null); 
        return accessor.accessToken; 
    } 
 } 
 import java.net.URL; 
 import java.security.KeyFactory; 
 import java.security.PrivateKey; 
 import java.security.spec.EncodedKeySpec; 
 import java.security.spec.PKCS8EncodedKeySpec; 
 import java.util.Collection; 
 import java.util.Map; 
 import com.google.gdata.client.GoogleService; 
 import com.google.gdata.client.authn.oauth.OAuthParameters; 
 import com.google.gdata.client.authn.oauth.OAuthRsaSha1Signer; 
 import com.google.gdata.client.authn.oauth.OAuthSigner; 
 import com.google.gdata.data.BaseEntry; 
 import com.google.gdata.data.BaseFeed; 
 import com.google.gdata.data.Feed; 
 import net.oauth.OAuth; 
 import net.oauth.OAuthConsumer; 
 import net.oauth.OAuthMessage; 
 import net.oauth.OAuthServiceProvider; 
 import net.oauth.client.OAuthClient; 
 import net.oauth.client.httpclient4.HttpClient4; 
 import net.oauth.example.desktop.MyGoogleService; 
 import net.oauth.signature.OAuthSignatureMethod; 
 import net.oauth.signature.RSA_SHA1; 

 public class GoogleOAuthExample { 
    //Note, use the private key of your self-signed X509 certificate. 
    private static final String PRIVATE_KEY = "XXXXXXXX"; 

    public static void main(String[] args) throws Exception { 
        KeyFactory fac = KeyFactory.getInstance("RSA"); 
        //PRIVATE_KEY is the private key of your self-signed X509 certificate. 
        EncodedKeySpec privKeySpec = new PKCS8EncodedKeySpec( 
		    OAuthSignatureMethod.decodeBase64(PRIVATE_KEY)); 
        fac = KeyFactory.getInstance("RSA"); 
        PrivateKey privateKey = fac.generatePrivate(privKeySpec); 
        OAuthServiceProvider serviceProvider = new OAuthServiceProvider( 
            //used for obtaining a request token 
			 //"https://www.google.com/accounts/OAuthGetRequestToken", 
	        //used for authorizing the request token 
            "https://www.google.com/accounts/OAuthAuthorizeToken", 
             //used for upgrading to an access token 
            "https://www.google.com/accounts/OAuthGetAccessToken"); 

        OAuthConsumer oauthConsumer = new OAuthConsumer(null 
            , "lszhy.weebly.com" //consumer key 
            , "hIsGnM+T4+86fKNesUtJq7Gs" //consumer secret 
            , serviceProvider); 

        oauthConsumer.setProperty(OAuth.OAUTH_SIGNATURE_METHOD, OAuth.RSA_SHA1); 
        oauthConsumer.setProperty(RSA_SHA1.PRIVATE_KEY, privateKey); 

        DesktopClient client = new DesktopClient(oauthConsumer); 
        client.setOAuthClient(new OAuthClient(new HttpClient4())); 
		
        Collection<? extends Map.Entry> parameters = 
		    OAuth.newList("scope","http://www.google.com/calendar/feeds/");
		
        String accessToken = client.getAccessToken(OAuthMessage.GET,parameters); 
		
		
        //Make an OAuth authorized request to Google 
		
        // Initialize the variables needed to make the request 
        URL feedUrl = new URL( 
		    "http://www.google.com/calendar/feeds/default/allcalendars/full");
        
        System.out.println("Sending request to " + feedUrl.toString()); 
        System.out.println(); 
        
        GoogleService googleService = new GoogleService("cl", "oauth-sample-app"); 

        OAuthSigner signer = new OAuthRsaSha1Signer(MyGoogleService.PRIVATE_KEY); 
        
        // Set the OAuth credentials which were obtained from the step above. 
        OAuthParameters para = new OAuthParameters(); 
        para.setOAuthConsumerKey("lszhy.weebly.com"); 
        para.setOAuthToken(accessToken); 
        googleService.setOAuthCredentials(para, signer); 
        
        // Make the request to Google 
        BaseFeed resultFeed = googleService.getFeed(feedUrl, Feed.class); 
        System.out.println("Response Data:");               
        System.out.println("=========================================="); 

        System.out.println("|TITLE: " + resultFeed.getTitle().getPlainText()); 
        if (resultFeed.getEntries().size() == 0) { 
           System.out.println("|\tNo entries found."); 
        } else { 
            for (int i = 0; i < resultFeed.getEntries().size(); i++) { 
               BaseEntry entry = (BaseEntry) resultFeed.getEntries().get(i); 
               System.out.println("|\t" + (i + 1) + ": "
                    + entry.getTitle().getPlainText()); 
            } 
        } 
        System.out.println("=========================================="); 	
    } 
 }

小结

OAuth 协议作为一种开放的，基于用户登录的授权认证方式，目前互联网很多 Open API 都对 OAuth 提供了支持，这包括 Google, Yahoo，Twitter 等。本文以 Google 为例子，介绍了 Java 桌面程序如何开发 OAuth 认证应用。在开发桌面应用访问 Web 资源这样一类程序时，一般通行的步骤是：使用 OAuth 做认证，然后使用获得的 OAuth Access Token，通过 REST API 访问用户在服务提供方的资源。

事实上，目前 OAuth 正通过许多实现（包括针对 Java、C#、Objective-C、Perl、PHP 及 Ruby 语言的实现）获得巨大的动力。大部分实现都由 OAuth 项目维护并放在 Google 代码库 (http://oauth.googlecode.com/svn/) 上。开发者可以利用这些 OAuth 类库编写自己需要的 OAuth 应用。

本文链接

OAuth介绍

2011-01-14T10:45:00Z

简介

OAuth (开放授权) 是一个开放标准，允许用户让第三方网站访问该用户在某一网站上存储的私密的资源（如照片，视频，联系人列表），而无需将用户名和密码提供给第三方网站。

OAuth允许用户提供一个令牌，而不是用户名和密码来访问他们存放在特定服务提供者的数据。每一个令牌授权一个特定的网站（例如，视频编辑网站)在特定的时段（例如，接下来的2小时内）内访问特定的资源（例如仅仅是某一相册中的视频）。这样，OAuth允许用户授权第三方网站访问他们存储在另外的服务提供者上的信息，而不需要分享他们的访问许可或他们数据的所有内容。

OAuth是OpenID的一个补充，但是完全不同的服务。

认证和授权过程

在认证和授权的过程中涉及的三方包括：

服务提供方，用户使用服务提供方来存储受保护的资源，如照片，视频，联系人列表。
用户，存放在服务提供方的受保护的资源的拥有者
客户端，要访问服务提供方资源的第三方应用，通常是网站，如提供照片打印服务的网站。在认证过程之前，客户端要向服务提供者申请客户端标识。

使用OAuth进行认证和授权的过程如下所示:

用户访问客户端的网站，想操作用户存放在服务提供方的资源。
客户端向服务提供方请求一个临时令牌。
服务提供方验证客户端的身份后，授予一个临时令牌。
客户端获得临时令牌后，将用户引导至服务提供方的授权页面请求用户授权。在这个过程中将临时令牌和客户端的回调连接发送给服务提供方。
用户在服务提供方的网页上输入用户名和密码，然后授权该客户端访问所请求的资源。
授权成功后，服务提供方引导用户返回客户端的网页。
客户端根据临时令牌从服务提供方那里获取访问令牌。
服务提供方根据临时令牌和用户的授权情况授予客户端访问令牌。
客户端使用获取的访问令牌访问存放在服务提供方上的受保护的资源。

以上资料整理自：http://zh.wikipedia.org/zh/OAuth

目前采用OAuth的API

Facebook的新的Graph API只支持OAuth 2.0，是这一新兴标准的最大实现：http://developers.facebook.com/docs/reference/api/（Facebook SDK for Android 协同 Facebook Platform 一起，隐藏了 OAuth 身份认证的复杂性：Facebook API 简介）

Twitter API Wiki：http://apiwiki.twitter.com/w/browse/#view=ViewFolder&param=OAuth

新浪微博API：http://open.t.sina.com.cn/wiki/index.php/OAuth

豆瓣API：http://www.douban.com/service/apidoc/auth

目前有6个Google Apps API支持OAuth登录机制：

本文链接

Facebook API 简介

2011-01-14T08:55:00Z

原文：http://www.ibm.com/developerworks/cn/xml/x-androidfacebookapi/index.html

Facebook Platform API 概述

在介绍 Facebook SDK for Android 之前，有必要了解一下 Facebook Platform 及其 API。据 Facebook 声称，Facebook Platform 允许任何人 “在 Facebook 和 Web 上构建社交应用程序”。为了允许您构建此类应用程序，Facebook 提供广泛的一组核心且高级的 API 和 SDK（参见参考资料）。

核心 Facebook Platform API 是 Graph API，它允许您从 Facebook 读写数据。Facebook 也具有 Old Rest API。新的 Graph API 将 API 范型从面向方法的从 Facebook 读写数据的方式更改为一种新的方式，即使用对象（比如说用户简介、好友、帖子、照片，诸如此类）及其相互之间的关系或连接。该方法简化了 Facebook API，使之处理对象时更加一致。注意，尽管 Graph API 是首选的 Facebook API，但是 Old REST API 仍然是活跃且受支持的。Graph 和 REST API 都适用于移动应用程序（包括原生和移动 web 应用程序），它们通过使用 WebViews 在原生应用程序中包含移动 web 内容。

Graph API 对象被分配一个惟一的 ID，很容易使用一个 URL 访问它，此 URL 可被进一步限定，以寻址一个特定的对象/连接。对象 URL 的一般结构类似如下： https://graph.facebook.com/OBJECT_ID/CONNECTION_TYPE，其中 OBJECT_ID 是对象的惟一 ID，CONNECTION_TYPE 是对象支持的一种连接类型。例如，一个页面支持以下连接：feed/wall、photos、notes、posts、members，等等。

利用 Graph API，您可以检索对象，删除对象和发布对象。您可以搜索、更新对象、过滤结果，甚至动态地发现对象的连接/关系。

默认情况下，应用程序对用户的公共数据具有访问权限。要访问私有数据，应用程序必须首先请求用户的权限（被称之为扩展权限）。Facebook 定义了大量权限，您可以在 Extended Permissions 页面了解它们（参见参考资料）。

Facebook SDK for Android 简介

既然您较好地了解了 Facebook Platform API，下面就来看一下 Facebook SDK for Android。

Facebook SDK for Android 是 Facebook Graph 和 Old REST API 的一个 Java 编程语言包装器。此 SDK 是开源的，宿主在 github 的 facebook / facebook-android-sdk 仓库中（参见参考资料）。注意，由于开源 SDK 的演变特性，它有望发生进一步的更改。SDK 发布于 Apache License, Version 2.0 之下。

Facebook SDK for Android 隐藏了前一节（Facebook Platform API 概述）中介绍的很多细节。这是通过提供表 1 中描述的 6 个 Java 类来实现的。

表 1. 包 com.facebook.android

类
说明

AsyncFacebookRunner
一个实现异步 Facebook API 调用的帮助器类

DialogError
一个封装对话框错误的类

Facebook
用于与 Facebook Platform API 交互的主 Facebook 类

FacebookError
一个封装 Facebook 错误的类

FbDialog
一个为 Facebook 对话框实现 WebView 的类

Util
一个带有大量实用方法的帮助器类

Facebook SDK for Android 也带来一些有用的例子，您可以用来作为自己应用程序的起点。

尤其有趣的是核心 Facebook 类和 Facebook Dialog 类，下面将更为详细地介绍它们。核心 Facebook 类封装了对用户进行授权、创建 Facebook 对话框、发出 API 请求、注销用户以及获得或设置访问和会话信息及状态的方法。Facebook Dialog 类实现了一个 WebView 及其创建它的方法以及用于处理 Facebook URL（状态）响应的逻辑。SDK 操作离不开对话框。SDK 提供两种方法进行身份认证，一种称之为单点登录，如果安装了的话，它使用原生的 Facebook 应用程序对话框，另一种是默认的 WebView 方法。本文我将重点介绍 WebView 方法。其余 SDK 类是帮助器类，用于封装错误信息或者提供整个 SDK 中使用的有用工具。

下面几节着重介绍一个典型 Facebook 应用程序的用例：

安装 Facebook SDK for Android
注册您的应用程序
创建 SampleApp
显示 Facebook 对话框
对用户进行授权
发出 API 请求

安装 Android SDK

您必须下载并安装 Eclipse 或者您喜欢的 IDE。此外，还必须安装 Android SDK。有关如何下载并安装 Eclipse 和 Android SDK 的信息，请参见 Android Developer 网站（参见参考资料）的 Download the Android SDK 页面。

安装 Facebook SDK for Android

Facebook SDK for Android 宿主在 github 的 facebook / facebook-android-sdk 仓库中。下载 SDK 源文件，将之解压到您的工作目录。启动 Eclipse，通过选择 File Menu -> New -> Project 创建一个 Android Project，并选中 Android Project。从 existing source 创建项目，并指向解压的源文件目录（参见下载获得源代码）。

注册您的应用程序

在开始之前，您必须注册您的 Facebook 应用程序并得到一个应用程序 ID (client_id) 和相关的密钥 (client_secret)。在进行不同的 Facebook API 调用时，会在您的应用程序中使用客户机 ID。

样例应用程序

样例应用程序（我将之简称为 SampleApp）展示了如何使用 Facebook SDK for Android。此应用程序包含单个文件，该文件实现 SampleApp 活动，使用一个屏幕来显示消息、Facebook 好友列表，以及用于登录/身份认证用户、获得好友列表和发布到已通过身份认证用户 (me) 涂鸦墙的菜单项。

在开始之前，请记住您必须像前面解释的那样将您的应用程序注册到 Facebook，还必须将 SampleApp.java 中的属性 APP_ID 设置为由 Facebook 提供的 client_id（参见清单 1 ）。

清单 1. 初始化应用程序 ID

// Set application ID to your registered app client_id
// See http://www.facebook.com/developers/createapp.php
public static final String APP_ID = ".....";

对于 Sample Application 屏幕，使用一种线性布局，包含一个 TextView（用于简单状态消息）、一个 ListView（用于显示从服务器检索到的 Facebook 好友列表）和一些菜单项（用于登录/身份认证用户、获得好友列表和发布到已通过身份认证用户 (me) 的涂鸦墙）。清单 2 展示了主 UI 屏幕布局的 XML UI 声明。

清单 2. 主屏幕 UI 声明

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout 
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:orientation="vertical"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    android:background="@drawable/black"
    >
    
    <TextView android:id="@+id/txt"     
        android:text="@string/hello"
        android:textColor="@drawable/white"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:paddingRight="10dp" 
        android:paddingLeft="10dp"
        android:layout_margin="10dp"
        android:textSize="10sp" 
        android:layout_marginTop="5px" 
        android:layout_marginBottom="5px"
        android:layout_marginRight="0px" 
        android:layout_marginLeft="0px"
        android:gravity="left"
    />
    
    <ListView  
        android:id="@+id/friendsview"
        android:layout_width="fill_parent" 
        android:layout_height="wrap_content"
        android:textFilterEnabled="true" 
    />
    <TextView 
        android:id="@id/android:empty"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:text="No data"
     />               
</LinearLayout>

清单 3 展示了 ListView 中每一行的 XML UI 声明。

清单 3. ListView 行 UI 声明

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout 
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="fill_parent"
    android:layout_height="?android:attr/listPreferredItemHeight"
    android:padding="10dip"
    >
     <TextView
         android:id="@+id/rowtext_top"
         android:layout_width="wrap_content"
         android:layout_height="wrap_content"
         android:gravity="center_vertical"
     />
</LinearLayout>

清单 4 展示了菜单项的 XML UI 声明。

清单 4. 菜单项 UI 声明

<menu xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:id="@+id/login" android:title="Login"/>
    <item android:id="@+id/getfriends" android:title="Get Friends"/>
    <item android:id="@+id/wallpost" android:title="Wall Post" />
</menu>

图 1 展示了 SampleApp 在登录之前（带有 Login 按钮）和之后（带有 Logout、Get Friends 和 Wall Post 按钮）XML UI 声明的结果。

图 1. SampleApp 屏幕布局

SampleApp onCreate() 方法在创建 SampleApp 实例时由 Android 平台调用。此方法执行一个基本的检查（以确保在继续之前已经设置了 App ID）、初始化 UI 资源和初始化 Facebook 会话实例（参见清单 5 ）。

清单 5. 初始化应用程序

/** Called when the activity is first created. */
@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    // Make sure the app client_app has been set
    if (APP_ID == null) {
        Util.showAlert(this, 
        "Warning", "Facebook Application ID must be set...");
    }

    // Initialize the content view
    setContentView(R.layout.main);
    // Get the status text line resource
    mText = (TextView) SampleApp.this.findViewById(R.id.txt);

    // Setup the ListView Adapter that is loaded when selecting "get friends"
    listView = (ListView) findViewById(R.id.friendsview);
    friendsArrayAdapter = new FriendsArrayAdapter(this, R.layout.rowlayout, friends);
    listView.setAdapter(friendsArrayAdapter);

    // Define a spinner used when loading the friends over the network
    mSpinner = new ProgressDialog(listView.getContext());
    mSpinner.requestWindowFeature(Window.FEATURE_NO_TITLE);
    mSpinner.setMessage("Loading...");

    // Initialize the Facebook session
    mFacebook = new Facebook(APP_ID);
    mAsyncRunner = new AsyncFacebookRunner(mFacebook);

}

应用程序流的其余部分通过菜单项由 UI 交互触发。定义了三个菜单项：1) login/logout（切换），2) get friends 和 3) post to the wall，如清单 4 所示。当用户选择一个菜单项时，应用程序就执行一个适当的操作。下面的清单展示了菜单项是如何处理的。清单 6 展示了如何通过具体化其 XML 定义而实例化菜单的。

清单 6. 创建菜单

/**
 * Invoked at the time to create the menu
 * @param the menu to create
 */
@Override
public boolean onCreateOptionsMenu(Menu menu) {
    MenuInflater inflater = getMenuInflater();
    inflater.inflate(R.menu.main_menu, menu);
    return true;
}

清单 7 展示了菜单项在显示之前是如何被修改的，就是说，根据实际情况显示适当的 "login" 或 "logout" 状态并启用/禁用 "get friends" 和 "post to wall"。

清单 7. 创建菜单

/**
 * Invoked when preparing to display the menu
 * @param menu is the menu to prepare
 */
@Override
public boolean onPrepareOptionsMenu(Menu menu) {
    MenuItem loginItem = menu.findItem(R.id.login);
    MenuItem postItem = menu.findItem(R.id.wallpost);
    MenuItem getfriendsItem = menu.findItem(R.id.getfriends);
    if (mFacebook.isSessionValid()) {
        loginItem.setTitle("Logout");
        postItem.setEnabled(true);
        getfriendsItem.setEnabled(true);
    } else {
        loginItem.setTitle("Login");
        postItem.setEnabled(false);
        getfriendsItem.setEnabled(false);
    }
    loginItem.setEnabled(true);
    return super.onPrepareOptionsMenu(menu);
}

清单 8 展示了菜单项是如何被处理的，以及适当的操作（login/logout、get friends、post to wall）是如何被调用的。

清单 8. 处理菜单选择

/**
 * Invoked when a menu item has been selected
 * @param item is the selected menu item
 */
@Override
public boolean onOptionsItemSelected(MenuItem item) {
    switch (item.getItemId()) {

        // Login/logout toggle
        case R.id.login:
            // Toggle the button state. 
            //  If coming from login transition to logout.
            if (mFacebook.isSessionValid()) {
                AsyncFacebookRunner asyncRunner = new AsyncFacebookRunner(mFacebook);
                asyncRunner.logout(this.getBaseContext(), new LogoutRequestListener());
            } else {
                // Toggle the button state. 
                //  If coming from logout transition to login (authorize).
                mFacebook.authorize(this, PERMISSIONS, new LoginDialogListener());
            }
            break;

        // Wall Post
        case R.id.wallpost: // Wall Post
            mFacebook.dialog(SampleApp.this, "stream.publish", new 
                                                  WallPostDialogListener());
            break;

        // Get Friend's List
        case R.id.getfriends: // Wall Post
            // Get the authenticated user's friends
            mSpinner.show();
            mAsyncRunner.request("me/friends", new FriendsRequestListener());
            break;

        default:
            return false;

    }
    return true;
}

应用程序使用很多回调来处理每个异步调用的状态。SampleApp 定义一个回调来处理 login 请求、logout 对话框、post to wall 对话框和 get friends 请求的成功或失败。您可以利用这个样例应用程序，并添加您自己的操作，遵循添加菜单和相应 Facebook 调用的相同模式，利用对应的回调来接收状态信息。

FriendsRequestListener 回调在发出 Facebook API 请求一节中介绍。最后一个回调是 MyDialogListener，它实现 Facebook SDK for Android DialogListener，这用于使用 SDK 基于 WebView 的对话框的 Facebook 请求，下一节中将会介绍。DialogListener 的实现者必须实现适当的完成逻辑；例如，这在 login 和 wall post 请求过程中使用。

显示 Facebook 对话框

对于诸如用户授权、分配权限和消息发布之类的用户交互，Facebook SDK for Android 依赖于 Facebook 基于 web/服务器的对话框。核心 SDK Facebook.java 类在为请求操作产生 UI 对话框时定义方法 dialog()（参见清单 9 ）。

清单 9. Facebook Dialog 方法

/**
 * Generate a UI dialog for the request action in the given Android context
 * with the provided parameters.
 */
public void dialog(
        Context context, 
        String action, 
        Bundle parameters,
        final DialogListener listener) {
    :
    :
}

此异步方法接受应用程序上下文的输入参数、执行的操作（比如 login、publish_stream、read_stream、offline_access）、特定请求或操作需要的参数和异步方法完成执行时调用的侦听器方法。该方法创建适当的 WebView 对话框。例如，要发布一个状态消息，需要调用核心 Facebook 类方法 dialog()，传递操作 stream.publish（参见清单 10 ）。

清单 10. 调用 dialog() 方法和处理回调

package com.myapp.facebook.android;
:

import com.facebook.android.*;
:

mFacebook = new Facebook(); // Facebook core
:

// Create a Facebook dialog (using the call asynchronous API)
mFacebook.dialog(
    this,
    "stream.publish", 
    new MyDialogListener());   

:
:

//
// My asynchronous dialog listener
//
public class MyDialogListener extends com.facebook.android.Facebook.DialogListener {

    public void onComplete(Bundle values) {

        final String postId = values.getString("post_id");

        if (postId != null) {

            // "Wall post made..."

        } else {
            // "No wall post made..."
        }

    }

    public void onFacebookError(FacebookError e) {...}
    public void onError(DialogError e) {...}
    public void onCancel() {...}

}

该调用的结果是 Facebook 基于 web 的 publish to wall 对话框，如图 2 所示。

图 2. 发布到涂鸦墙

这是熟悉的发布到用户涂鸦墙的 Web 页面，与 Facebook 提供的一样。用户可以跳过或者继续前进并发布消息。这种在同一移动应用程序中混合使用原生和 web 内容是混合应用程序强大之处的很好示例。

对用户进行授权

Facebook Platform 对 OAuth 2.0 身份认证提供支持，也支持一种较老的、定制的授权签名方案。编写新应用程序时应该避免使用老的身份认证方案，因为对这种老方案的支持很快就会取消了。更多有关 OAuth 的信息，请参见参考资料中的 OAuth 2.0 Protocol 规范。

Facebook SDK for Android 协同 Facebook Platform 一起，隐藏了 OAuth 身份认证的复杂性，如图 3 所示。

图 3. OAuth 2.0 Protocol (IETF)

Facebook SDK for Android 采用移动 web 身份认证方法，而不是采用原生方法。注意，未来版本的 SDK 有可能对 OAuth 提供原生的 Android 支持。对于此方法，SDK 在 WebView 中使用 Facebook 基于 web 的身份认证对话框。这是一个有趣的方法，理由如下：

它减少了对应用程序实现 OAuth 原生功能的复杂性。
更为重要的是，它通过显示跟在常规浏览器上使用 Facebook 时看到的相同的标准而熟悉的登录和分配权限对话框，赢得用户的信任。

该方法的一个优点是，它有时可能感觉比纯粹的原生实现要慢一些。为此，SDK 包含一个备选的身份认证/登录方法，即使用原生 Facebook 应用程序的单点登录。这就是说，如果官方 Facebook 原生应用程序安装在手机上，那么 Facebook SDK for Android 可以使用它的身份认证/登录活动。但是要使之工作，您必须首先签署您的应用程序（参见参考资料中 Frank Ableson 的文章 “Introduction to Android Security”），然后生成一个签名或密钥散列（参见清单 11 ）。

清单 11. 生成应用程序密钥散列

keytool -exportcert -alias [alias] -keystore [keystore] | openssl sha1 -binary |
openssl base64

注意，清单 11 中的代码通常在一行中。这里出于格式化目的，将它分成了多行。

然后您必须在图 4 所示 mobile and devices 部分下面（查看图 4 的大图），为您的特定应用程序注册 Facebook 上生成的密钥散列。

图 4. 输入应用程序密钥散列

一旦注册了，您就必须为您的应用程序定义一个 “活动结果处理程序”；实现 onActivityResult(...)（您必须在它上面调用方法 facebook.authorizeCallback(...)，如清单 12 所示）。

清单 12. 清单 12. 定义一个活动结果处理程序

@Override
public void onActivityResult(int requestCode, int resultCode, Intent data) {
  super.onActivityResult(requestCode, resultCode, data);
  facebook.authorizeCallback(requestCode, resultCode, data);
  :
  :
  // ... Other onActivityResult steps per your app...
}

注意，如果没有定义单点登录方法，或者没有给出原生 Facebook 应用程序，那么 SDK 将默认对身份认证/登录使用 WebView 方法。本文其余部分将着重介绍这种默认方法。

正如前面所提到的，默认情况下，应用程序对用户简介中的所有公共数据具有访问权限。要访问私有数据，应用程序必须请求权限，并由用户对应用程序授予权限，才能进行访问。获得对私有数据进行访问的权限被称作扩展权限。

Facebook SDK for Android authorize() 方法实现 OAuth 2.0 User-Agent 流，以检索一个访问令牌，用于后续的 API 请求中。该方法开始一个活动（原生的 Facebook 应用程序，如果给出并配置了的话）或者一个 WebView 对话框，以提示用户输入凭证（身份认证）和权限（授权），参见清单 13 ）。

清单 13.授权方法

/**
 * Authorize method that grants custom permissions.
 */
public void authorize(Activity activity, String[] permissions,
        final DialogListener listener) {
    :
    :
}

注意，为了单点登录身份认证正确工作，您必须在 onActivityResult() 函数中包含一个对 authorizeCallback() 方法的调用。

回想一下清单 8 中登录菜单项是如何利用权限调用 authorize() 方法的。

清单 14 展示了如何利用权限调用 authorize() 方法，以写入内容。它也具有权限来写评论和喜好（publish_stream）、阅读用户的提要、执行搜索（read_stream）和让访问凭证长期有效（offline_access）。不要忘记设置您的 APP_ID。

清单 14. 利用权限调用 authorize() 方法

package com.myapp.facebook.android;
:
import com.facebook.android.*;
:

public static final String APP_ID = "13234...";

private static final String[] PERMISSIONS = new String[] {"publish_stream", 
        "read_stream", "offline_access"};

:
:

// Call the authorization method
mFacebook.authorize(
    getContext(), 
    APP_ID, 
    mPermissions,
    new MyLoginDialogListener());

:
:

// Asynchronous Callback when authorization completes
private final class MyLoginDialogListener implements com.facebook.android
          .Facebook.DialogListener {

    public void onComplete(Bundle values) {...} // here enable logout
    public void onFacebookError(FacebookError error) {...}
    public void onError(DialogError error) {...}
    public void onCancel() {...}
}

authorize() 方法在内部调用前面介绍过的 dialog() 方法，但是这一次它传递一个针对操作的 Login 请求。在 Facebook Platform 及其 OAuth 实现的帮助下，authorize() 方法也处理到 Facebook 的身份认证请求，并返回整个 Facebook 会话和 API 调用期间使用的 access_token：https://graph.facebook.com/ID?access_token=...。

有关身份认证如何工作的详细信息，请参见参考资料中的 Facebook Authentication 页面。

调用 authorize() 方法导致图 5 中基于 WebView 的对话框。

图 5. 授权和权限屏幕 (WebView)

用户登录之后，会被提示按照应用程序的请求输入权限（email 或电话信息和密码）。用户可以允许或拒绝应用程序权限访问她的 Facebook 和执行如下操作：访问基本信息、发布到用户的涂鸦墙、访问 News Feed 中的帖子或者访问用户数据。

发出 Facebook API 请求

核心 Facebook 类为 Old REST 和 Graph API 调用实现很多 request() 方法。此外，SDK 提供帮助器封装器类来异步地发出核心请求 API 调用。

作为一个 API 请求的例子，您将发出一个请求，为经过身份认证的用户检索好友。回想一下 Graph API 的结构：

https://graph.facebook.com/ID/CONNECTION_TYPE

另外，回想一下特殊的 ID me，它用于识别经过身份认证的用户，此用户已经登录：https://graph.facebook.com/me/friends。

清单 15 展示了一个来自清单 8 的代码片段，即如何实现 request() 方法调用。在本例中，您使用 AsyncFacebookRunner.request(...) 方法，这是一个帮助器封装器方法，它通过运行在自己的线程中，使得底层的请求方法是异步的。这一步是为了避免阻塞主 UI 线程。

清单 15.异步地分配请求

// Get Friend's List
case R.id.getfriends: // Wall Post
    // Get the authenticated user's friends
    mSpinner.show();
    mAsyncRunner.request("me/friends", new FriendsRequestListener());
    break;

FriendsRequestListener onComplete(...) 回调在取得好友列表的请求执行完成时被调用。该方法解析返回的好友列表 JSON。注意，清单 16 并没有展示所有实现的方法。

清单 16. 处理取得好友请求

/**
 * FriendsRequestListener implements a request lister/callback
 *  for "get friends" requests
 */
public class FriendsRequestListener implements 
        com.facebook.android.AsyncFacebookRunner.RequestListener {

    /**
     * Called when the request to get friends has been completed.
     * Retrieve and parse and display the JSON stream.
     */
    public void onComplete(final String response) {
        mSpinner.dismiss();
        try {
            // process the response here: executed in background thread
            Log.d("Facebook-Example-Friends Request", "response.length(): " + 
                                                                response.length());
            Log.d("Facebook-Example-Friends Request", "Response: " + response);

            final JSONObject json = new JSONObject(response);
            JSONArray d = json.getJSONArray("data");
            int l = (d != null ? d.length() : 0);
            Log.d("Facebook-Example-Friends Request", "d.length(): " + l);

            for (int i=0; i<l; i++) {
                JSONObject o = d.getJSONObject(i);
                String n = o.getString("name");
                String id = o.getString("id");
                Friend f = new Friend();
                f.id = id;
                f.name = n;
                friends.add(f);
            }

            // Only the original owner thread can touch its views
            SampleApp.this.runOnUiThread(new Runnable() {
                public void run() {
                    friendsArrayAdapter = new FriendsArrayAdapter(
                            SampleApp.this, R.layout.rowlayout, friends);
                    listView.setAdapter(friendsArrayAdapter);
                    friendsArrayAdapter.notifyDataSetChanged();
                }
            });
        } catch (JSONException e) {
            Log.w("Facebook-Example", "JSON Error in response");
        }
    }

    :
    :
}

根据您的应用程序的要求，来自 Facebook 服务器的响应（JSON 格式）必须相应地被解析和处理。您可能决定通过使用 WebView 或者跟本 SampleApp（参见图 6 ）中一样使用 ListView 显示这样的信息。

图 6. 显示结果

结束语

在本文中，您学习了 Facebook API。首先是 Facebook Platform 及其 API 的一般概述，然后是 Facebook SDK for Android 和一个样例应用程序。学习本文之后，您更好地了解了各种不同的 Facebook API 以及如何开始为 Android 平台编写 Facebook 应用程序。

本文链接

在 Android 应用程序中使用 Internet 数据

2011-01-13T07:21:00Z

原文：http://www.ibm.com/developerworks/cn/xml/x-dataAndroid/index.html

Android 应用程序必须访问位于 Internet 上的数据，而 Internet 数据可以有几种不同的格式。本文将介绍在 Android 应用程序中如何使用三种数据格式：

XML
JSON
Google 的 protocol buffers

首先开发一个 Web 服务，将 CSV 数据转换成 XML、JSON 和 protocol-buffers 格式。然后构建一个样例 Android 应用程序，可以从 Web 服务中以任何一种格式提取数据并将其解析并显示给用户。

要进行本文中的练习，您需要最新的 Android SDK（参见参考资料）和 Android 2.2 平台。SDK 还要求您安装一个 Java™ 开发包（JDK）；本文中使用了 JDK 1.6.0_17。您不需要有 Android 物理设备；所有代码都将在 SDK 的 Android 仿真器中运行。本文并没有教您如何进行 Android 开发，因此建议您熟悉 Android 编程。当然，只凭借 Java 编程语言的知识也可以完成本文的学习。

您还需要一个 Java web 应用程序服务器来运行 Android 应用程序使用的 Web 服务。此外，也可以将服务器端代码部署到 Google App Engine。参见下载部分获得完整的源代码。

Day Trader 应用程序

您将开发一个简单的 Android 应用程序，叫做 Day Trader。Day Trader 允许用户输入一个或更多的股票代码并获取其所代表股票的最新价格信息。用户可以指定数据使用的格式：XML、JSON 或 protocol buffers。实际的 Android 应用程序通常不会提供此选择，但是通过实现此功能，您可以了解如何让您的应用程序处理每一种格式。图 1 展示了 Day Trader 用户界面：

图 1. 运行中的 Day Trader 应用程序

文本框及其旁边的 Add Stock 按钮允许用户输入感兴趣的每支股票的代码。用户按下 Download Stock Data 按钮后，会从服务器请求所有这些股票的数据，在应用程序中解析并显示在屏幕上。默认情况下，获取的是 XML 数据。通过菜单，您可以在 XML、JSON 或 protocol buffers 数据格式间切换。

清单 1 显示用于创建图 1 中所示 UI 的布局 XML：

清单 1. Day Trader 布局 XML

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:orientation="vertical"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    >
    <LinearLayout android:orientation="horizontal" 
        android:layout_width="fill_parent" 
        android:layout_height="wrap_content">
        <EditText android:id="@+id/symbol" android:layout_width="wrap_content"
            android:layout_height="wrap_content" android:width="120dip"/>
        <Button android:id="@+id/addBtn" android:layout_width="wrap_content"
            android:layout_height="wrap_content" 
            android:text="@string/addBtnLbl"/>
    </LinearLayout>
    <LinearLayout android:orientation="horizontal" 
        android:layout_width="fill_parent" 
        android:layout_height="wrap_content">
        <TextView android:layout_width="wrap_content" 
            android:layout_height="wrap_content" android:id="@+id/symList" />
        <Button android:id="@+id/dlBtn" android:layout_width="wrap_content" 
            android:layout_height="wrap_content" 
            android:text="@string/dlBtnLbl"
        />
       </LinearLayout>
    <ListView android:id="@android:id/list" 
        android:layout_height="fill_parent" android:layout_width="fill_parent"
        android:layout_weight="1"
        />
</LinearLayout>

清单 1 中的大部分代码都简单明了。可以看到几个小部件创建了图 1 所示的输入和按钮。还会看到一个 ListView，Android 小部件中真正的瑞士军刀。此 ListView 将用从服务器下载的股票数据填充。清单 2 显示了控制该视图的 Activity：

清单 2. Day Trader 主活动

public class Main extends ListActivity {

    private int mode = XML; // default
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);
        final EditText input = (EditText) findViewById(R.id.symbol);
        final TextView symbolsList = (TextView) findViewById(R.id.symList);
        final Button addButton = (Button) findViewById(R.id.addBtn);
        final Button dlButton = (Button) findViewById(R.id.dlBtn);
        addButton.setOnClickListener(new OnClickListener(){
            public void onClick(View v) {
                String newSymbol = input.getText().toString();
                if (symbolsList.getText() == null || 
                        symbolsList.getText().length() == 0){
                    symbolsList.setText(newSymbol);
                } else {
                    StringBuilder sb = 
                                  new StringBuilder(symbolsList.getText());
                    sb.append(",");
                    sb.append(newSymbol);
                    symbolsList.setText(sb.toString());
                }
                input.setText("");
            }
        });
        dlButton.setOnClickListener(new OnClickListener(){
            public void onClick(View v) {
                String symList = symbolsList.getText().toString();
                String[] symbols = symList.split(",");
                symbolsList.setText("");
                switch (mode){
                case JSON :
                    new StockJsonParser().execute(symbols);
                    break;
                case PROTOBUF :
                    new StockProtoBufParser().execute(symbols);
                    break;
                default :
                    new StockXmlParser().execute(symbols);
                    break;
                }
            }
        });
    }
}

此 Activity 设置了清单 1 中 XML 文件的布局，它将几个事件处理程序连接起来。首先，对于 Add Stock 按钮而言，代码读取文本框中的代码并将其添加到 symList TextView 中，用逗号分隔每个代码。接下来，对于 Download 按钮而言，处理程序从 symList TextView 中读取数据，然后 —基于 mode 变量— 使用三个不同的类之一从服务器下载数据。菜单设置 mode 变量的值；这个代码不是很重要，因此我在清单 2 中省略了它。在了解各种数据下载/解析类之前，我先为您展示一下服务器如何提供此数据。

提供股票数据

应用程序服务器需要能够做两件事。第一，它必须获取股票代码列表并检索它们的数据。然后，它需要接受一个格式参数并基于该格式编码数据。对于 XML 和 JSON 格式而言，该服务器将返回作为文本的串行化的股票数据。对于 protocol buffers 而言，它必须发送二进制数据。清单 3 显示了处理这些步骤的 servlet：

清单 3. Stock Broker servlet

public class StockBrokerServlet extends HttpServlet {
    public void doGet(HttpServletRequest request, 
          HttpServletResponse response) throws IOException {
        String[] symbols = request.getParameterValues("stock");
        List<Stock> stocks = getStocks(symbols);
        String format = request.getParameter("format");
        String data = "";
        if (format == null || format.equalsIgnoreCase("xml")){
            data = Stock.toXml(stocks);
            response.setContentType("text/xml");    
        } else if (format.equalsIgnoreCase("json")){
            data = Stock.toJson(stocks);
            response.setContentType("application/json");
        } else if (format.equalsIgnoreCase("protobuf")){
            Portfolio p = Stock.toProtoBuf(stocks);
            response.setContentType("application/octet-stream");
            response.setContentLength(p.getSerializedSize());
            p.writeTo(response.getOutputStream());
            response.flushBuffer();
            return;
        }
        response.setContentLength(data.length());
        response.getWriter().print(data);
        response.flushBuffer();
        response.getWriter().close();
    }

    public List<Stock> getStocks(String... symbols) throws IOException{
        StringBuilder sb = new StringBuilder();
        for (String symbol : symbols){
            sb.append(symbol);
            sb.append('+');
        }
        sb.deleteCharAt(sb.length() - 1);
        String urlStr = 
                "http://finance.yahoo.com/d/quotes.csv?f=sb2n&s=" + 
                    sb.toString();
        URL url = new URL(urlStr);
        HttpURLConnection conn = 
                (HttpURLConnection) url.openConnection();
        BufferedReader reader = new BufferedReader(
                new InputStreamReader(conn.getInputStream()));
        String quote = reader.readLine();
        List<Stock> stocks = new ArrayList<Stock>(symbols.length);
        while (quote != null){
            String[] values = quote.split(",");
            Stock s = 
                      new Stock(values[0], values[2],
                           Double.parseDouble(values[1]));
            stocks.add(s);
            quote = reader.readLine();
        }
        return stocks;
    }
}

这是一个简单的 Java servlet，只支持 HTTP GET 请求。它读入股票的值和格式请求参数。然后调用 getStocks() 方法。该方法调用 Yahoo! Finance 获取股票数据。Yahoo! 只支持 CSV 格式的数据，因此 getStocks() 方法将其解析到一个 Stock 对象列表。清单 4 展示了这个简单的数据结构：

清单 4. 股票数据结构

public class Stock {    
    private final String symbol;
    private final String name;
    private final double price;
      //getters and setters omitted

    public String toXml(){
        return "<stock><symbol>" + symbol + 
"</symbol><name><![CDATA[" +
            name + "]]></name><price>" + price + 
"</price></stock>";
    }

    public String toJson(){
        return "{ 'stock' : { 'symbol' : " +symbol +", 'name':" + name + 
            ", 'price': '" + price + "'}}";
    }

    public static String toXml(List<Stock> stocks){
        StringBuilder xml = new StringBuilder("<stocks>");
        for (Stock s : stocks){
            xml.append(s.toXml());
        }
        xml.append("</stocks>");
        return xml.toString();
    }

    public static String toJson(List<Stock> stocks){
        StringBuilder json = new StringBuilder("{'stocks' : [");
        for (Stock s : stocks){
            json.append(s.toJson());
            json.append(',');
        }
        json.deleteCharAt(json.length() - 1);
        json.append("]}");
        return json.toString();
    }
}

每个 Stock 都有三个属性— symbol、name 和 price — 和几个便捷的方法，以便将其自己转换成 XML 字符串或 JSON 字符串。它提供了一个工具方法，用于将 Stock 对象列表转换成 XML 或 JSON。回到清单 3，根据格式请求参数，Stock 对象列表被转换成 XML 或 JSON 字符串并被发送回客户端。

XML 和 JSON 用例非常类似和直接。对于 protocol buffers，您必须生成 protocol buffers 格式的代码读写对象。为此，您需要使用 protocol buffers 规范格式定义数据结构。清单 5 展示了一个示例：

清单 5. 股票的 Protocol buffers 消息

package stocks;

option java_package = "org.developerworks.stocks";

message Quote{
    required string symbol = 1;
    required string name = 2;
    required double price = 3;
}

message Portfolio{
    repeated Quote quote = 1;
}

protocol buffers 消息格式类似于接口描述语言 (IDL)，它与语言无关，因此可以将其与各种语言一起使用。在本例中，运行 protocol buffers 编译器（protoc）将清单 5 中的代码编译成要用于客户端和服务器的 Java 类。有关将 protocol buffers 消息编译成 Java 类的详细信息，请参阅 Protocol Buffers Developer Guide（参见参考资料）。

在清单 3 中，一个名为 toProtoBuf() 的方法将 Stock 对象列表转换成一个 Portfolio 消息。清单 6 展示了该方法的实现：

清单 6. 创建组合消息

public static Stocks.Portfolio toProtoBuf(List<Stock> stocks){
    List<Stocks.Quote> quotes = new ArrayList<Stocks.Quote>(stocks.size());
    for (Stock s : stocks){
        Quote q = 
            Quote.newBuilder()
                .setName(s.name)
                .setSymbol(s.symbol)
                .setPrice(s.price)
                .build();
        quotes.add(q);
    }
    return Portfolio.newBuilder().addAllQuote(quotes).build();
}

清单 6 中的代码使用了从清单 5 中的消息生成的代码 — Quote 和 Portfolio 类。只需构建来自每个 Stock 对象的 Quote，然后将其添加到清单 3 中返回到 servlet 的 Portfolio 对象即可。在清单 3 中，servlet 直接打开到客户端的流并使用生成的代码编写到流的二进制协议 buffers 数据。

现在，您了解了服务器如何创建要发送到 Android 应用程序的数据。接下来将学习应用程序如何解析此数据。

使用数据格式

清单 2 中的主 Activity 需要使用服务器可以发送的各种格式的数据。它还需要请求适当格式的数据并且数据一旦解析，就用它来填充其 ListView。因此，无论数据格式是什么，大部分功能都是通用的。

首先，创建一个抽象的基类，封装此通用功能，如清单 7 所示：

清单 7. 数据解析器基类

abstract class BaseStockParser extends AsyncTask<String, Integer, Stock[]>{
    String urlStr = "http://protostocks.appspot.com/stockbroker?format=";

    protected BaseStockParser(String format){
        urlStr += format;
    }

    private String makeUrlString(String... symbols) {
        StringBuilder sb = new StringBuilder(urlStr);
        for (int i=0;i<symbols.length;i++){
            sb.append("&stock=");
            sb.append(symbols[i]);
        }
        return sb.toString();
    }

    protected InputStream getData(String[] symbols) throws Exception{
        HttpClient client = new DefaultHttpClient();
        HttpGet request = new HttpGet(new URI(makeUrlString(symbols)));

        HttpResponse response = client.execute(request);
        return response.getEntity().getContent();
    }

    @Override
    protected void onPostExecute(Stock[] stocks){
        ArrayAdapter<Stock> adapter = 
            new ArrayAdapter<Stock>(Main.this, R.layout.stock, 
                      stocks );
        setListAdapter(adapter);
    }
}

清单 7 中的基类扩展了 android.os.AsyncTask。这是一个常用的用于异步操作的类。它抽象出线程和处理程序的创建，用于请求主 UI 线程。它是基于其输入和输出数据类型参数化的。对于所有解析器而言，输入总是一样的：股票代码字符串。输出也是一样的：Stock 对象数组。基类获取 format，这是一个指定了要使用的数据格式的字符串。然后提供一个方法，发出适当的 HTTP 请求并返回一个流响应。最后，它覆盖 AsyncTask 的 onPostExecute() 方法并使用从解析器返回的数据为 Activity 的 ListView 创建一个 Adapter。

现在看到三个解析器的功能是通用的。我将为您展示更具体的解析代码，从 XML 解析器开始。

用 SAX 解析 XML

Android SDK 提供了几种使用 XML 的方式，包括标准 DOM 和 SAX。对于一些对内存密集型情况，可以使用 SDK 的 pull-parser。大部分时候，SAX 是最快的方式。Android 包括一些便捷的 API 使得使用 SAX 更轻松。清单 8 显示了 Day Trader 应用程序的 XML 解析器：

清单 8. XML 解析器实现

private class StockXmlParser extends BaseStockParser{
    public StockXmlParser(){
        super("xml");
    }

    @Override
    protected Stock[] doInBackground(String... symbols) {
        ArrayList<Stock> stocks = new ArrayList<Stock>(symbols.length);
        try{
            ContentHandler handler = newHandler(stocks);
            Xml.parse(getData(symbols), Xml.Encoding.UTF_8, handler);
        } catch (Exception e){
            Log.e("DayTrader", "Exception getting XML data", e);
        }
        Stock[] array = new Stock[symbols.length];
        return stocks.toArray(array);
    }

    private ContentHandler newHandler(final ArrayList<Stock> stocks){
        RootElement root = new RootElement("stocks");
        Element stock = root.getChild("stock");
        final Stock currentStock = new Stock();
        stock.setEndElementListener(
            new EndElementListener(){
                public void end() {
                    stocks.add((Stock) currentStock.clone());
                }
            }
        );
        stock.getChild("name").setEndTextElementListener(
            new EndTextElementListener(){
                public void end(String body) {
                    currentStock.setName(body);
                }
            }
        );
        stock.getChild("symbol").setEndTextElementListener(
            new EndTextElementListener(){
                public void end(String body) {
                    currentStock.setSymbol(body);
                }
            }
        );
        stock.getChild("price").setEndTextElementListener(
            new EndTextElementListener(){
                public void end(String body) {
                            currentStock.setPrice(Double.parseDouble(body));
                }
            }
        );
        return root.getContentHandler();
    }
}

清单 8 中的大部分代码都在 newHandler() 方法中，该方法创建一个 ContentHandler。如果熟悉 SAX 解析，会知道 ContentHandler 通过响应 SAX 解析器触发的各种事件创建解析数据。newHandler() 方法使用 Android 便捷 API 指定使用事件处理程序的 ContentHandler。代码只是侦听在解析器遇到各种标记时触发的事件，然后选取数据，放到 Stock 对象列表中。创建 ContentHandler 后，调用 Xml.parse() 方法来解析基类提供的 InputStream 并返回 Stock 对象数组。这是快速解析 XML 的方法，但是 —即使使用 Android 提供的便捷 API— 它也是非常冗长的。

使用 JSON

XML 是 Android 上的一等公民，鉴于依赖于 XML 的 Web 服务的数量，这是个好事。很多服务还支持另一个流行格式 JSON。它通常比 XML 简洁一些，但也是人们可读的，使得它更易于使用，并且可以更轻松地将其用于调试使用它的应用程序。Android 包括一个 JSON 解析器。（您可以从 JSON.org 网站获得该解析器，只是要去除几个手机不需要的类）。清单 9 显示了使用中的解析器：

清单 9. JSON 解析器实现

private class StockJsonParser extends BaseStockParser{
    public StockJsonParser(){
        super("json");
    }
    @Override
    protected Stock[] doInBackground(String... symbols) {
        Stock[] stocks = new Stock[symbols.length];
        try{
            StringBuilder json = new StringBuilder();
            BufferedReader reader = 
                new BufferedReader(
                            new InputStreamReader(getData(symbols)));
            String line = reader.readLine();
            while (line != null){
                json.append(line);
                line = reader.readLine();
            }
            JSONObject jsonObj = new JSONObject(json.toString());
            JSONArray stockArray = jsonObj.getJSONArray("stocks");
            for (int i=0;i<stocks.length;i++){
                JSONObject object = 
                    stockArray.getJSONObject(i).getJSONObject("stock");
                stocks[i] = new Stock(object.getString("symbol"), 
                        object.getString("name"), 
                        object.getDouble("price"));
            }
        } catch (Exception e){
            Log.e("DayTrader", "Exception getting JSON data", e);
        }
        return stocks;
    }
}

可以看到在 Android 中使用 JSON 解析器是多么简单。您将来自服务器的流转换成传递给 JSON 解析器的字符串。您遍历对象图并创建 Stock 对象数组。如果使用过 XML DOM 解析，这看起来很类似，因为编程模型几乎一样。

像 DOM 一样，JSON 解析器可以用于内存密集型应用。在清单 9 中，所有来自服务器的数据都表示为字符串，然后作为 JSONObject，最后作为 Stock 对象数组。换句话说，同一数据通过三种不同的方式表示。可以看到，对于大量数据而言，这可能是个问题。当然，一旦到达方法末尾，这三种数据表示方式中的两种都会落在范围之外，被垃圾回收器回收。但是，只是触发更频繁的垃圾回收可能会对用户体验带来负面影响，造成处理速度下降。如果内存效率和性能很重要，使用 protocol buffers 的解析器可能是个较好的选择。

使用 protocol buffers 处理二进制

Protocol buffers 是一个由 Google 开发的与语言无关的数据串行化格式，旨在比 XML 更快地通过网络传送数据。它是 Google 用于服务器对服务器调用的事实标准。Google 将该格式及其用于 C++、Java 和 Python 编程语言的绑定工具以开源方式提供。

在清单 3 和清单 6 中看到 protocol buffers 是二进制格式。如您所料，这使得数据很简洁。如果在客户端和服务器端启用 gzip 压缩，在使用 XML 和 JSON 时通常也可以得到类似的消息大小，但是 protocol buffers 仍然有一些大小上的优势。它还是一种可以迅速解析的格式。最后，它提供了一个相当简单的 API。清单 10 显示了一个示例解析器实现：

清单 10. Protocol buffers 解析器实现

private class StockProtoBufParser extends BaseStockParser{
    public StockProtoBufParser(){
        super("protobuf");
    }

    @Override
    protected Stock[] doInBackground(String... symbols) {
        Stock[] stocks = new Stock[symbols.length];
        try{
            Stocks.Portfolio portfolio = 
                Stocks.Portfolio.parseFrom(getData(symbols));
            for (int i=0;i<symbols.length;i++){
                stocks[i] = Stock.fromQuote(portfolio.getQuote(i));
            }
        } catch (Exception e){
            Log.e("DayTrader", "Exception getting ProtocolBuffer data", e);
        }
        return stocks;
    }
}

如清单 3 所示，您可以使用 protocol buffers 编译器生成的 helper 类。这与服务器使用的 helper 类相同。可以编译它一次，然后在服务器和客户端共享它。这样，您可以更轻松地直接从服务器的流读取数据并将其转换成 Stock 对象数组。这种简单编程也具有非常出色的性能。现在看一下此性能与 XML 和 JSON 的比较。

性能比较

比较性能通常涉及某种微基准测试，此类基准测试很容易产生偏见或无意间得到不正确的结果。即使以公平方式设计微基准测试，很多随机因素也会对结果产生影响。尽管有这些问题，我还是要使用这样的微基准测试来比较 XML（大约 1300 ms）、JSON（大约 1150 ms）和 protocol buffers（大约 750 ms）。基准测试向服务器发送了一个关于 200 个股票的请求并测量了从发出请求到用于创建 ListView 的 Adapter 的数据准备就绪所需的时间量。对每个数据格式在两个设备上进行 50 次这样的操作：一个 Motorola Droid 和一个 HTC Evo，两个都通过 3G 网络。图 2 显示了结果：

图 2. 比较数据格式速度

图 2 显示出，在此基准测试中 protocol buffers（大约 750 ms）比 XML （大约 1300 ms）几乎快两倍。很多因素影响着数据通过网络和被手持设备处理的性能。一个明显的因素是通过网络的数据量。二进制格式的 protocol buffers 比文本格式的 XML 和 JSON 在通过网络时小得多。然而，文本格式可以使用 gzip 进行有效地压缩，这是 Web 服务器和 Android 设备都支持的标准技术。图 3 显示了在打开和关闭 gzip 时通过网络的数据大小：

图 3. 不同格式的数据大小

图 3 应该增加了您对 XML 和 JSON 之类的文本内容的压缩效果的喜爱（更不用说 Web 格式、HTML、JavaScript 和 CSS 了）。protocol buffers 数据（大约 6KB）比原始 XML（大约 17.5KB）或 JSON（大约 13.5KB）数据小得多。但是一旦进行了压缩， JSON 和 XML（都是大约 3KB）实际上比 protocol buffers 小很多了。在本例中，它们都接近于 protocol-buffers 编码消息大小的一半了。

回到图 2，速度的不同显然不能由通过网络的消息大小解释。protocol-buffers 消息比 XML 或 JSON 编码的消息大，但是通过使用 protocol buffers，您仍然能够削减半秒钟的用户等待时间。这是否意味着应该在 Android 应用程序中使用 protocol buffers 呢？这样的决定很少是固定的。如果要发送的数据量很小，则三种格式间的差异也不大。对于大量数据而言，protocol buffers 可能会有所不同。但是，像这样精心设计的基准测试无法替代对您自己的应用程序的测试。

结束语

本文介绍了如何使用 Internet 上流行的两种数据格式 XML 和 JSON 的方方面面。还讲到了第三种可能性，protocol buffers。像软件工程中的其他内容一样，选择技术主要就是权衡利弊。当您为一个局限的环境（比如 Android）开发时，这些决定的结果往往被放大了。我希望您现在拥有的关于这些后果的额外知识能够帮助您创建出色的 Android 应用程序。

本文链接