INTRODUCTION

Zhikai Wang/www.heteroclinic.net Aug 21,2013

Please read the companion READMEnLICENSE.txt.

Foaken as a software project is a tutorial project about how to handle Facebook Access Token for Java Desktop Application. The result implements the basic functions that are compatible with the up-to-date, August 20, 2013, Facebook Application Programming Interface (API). With the assistance other advanced packages, it will provide a handy template so Java developers, big data researchers, social network professionals (market research, statistics, poll etc) can kick-start with the minimum effort. This project will be easy to be adapted to fit other social network API.

1.1 Motivation
Project Friends Torus, in progress, is a bundle of software to visualize social network using 3D computer graphics. In this project, we need a Java implementation to communicate with Facebook API. Typically, a 3D computer graphics program is a desktop application or a native program. At the same time, Facebook API is highly dependent on Web browser as a platform and requires Javascript support. The most important is, during the authentication progress, Facebook security mechanism (including SSL/https) will not allow an intermediate application stand in between. After the authentication, the client application, a browser, will get an access token for further operation. A redirecting URL preset in Facebook application setting panel will re-direct the client Web browser. The access token is appended to the above mentioned URL. This requires an inter-process communication mechanism to pass the token string from Web browser to desktop application. We may put all Web browser's functionalities (must have Javascript support) in the desktop application, or we put the desktop application in a Web browser as a plug-in. Neither of the two approaches seems to be feasible for compatibility, portability, given time constraint etc. We take a compromised approach by starting a mini Web server to communicate with client Web browser. Above all, if this project helps us understand the work flow, it would not be difficult to integrate the functionality taking the two approaches mentioned above.
Our mini Web server/inter process communication experiment is also preparing for the concept 'rendering as a service, rendering as stream' -- RSRS. The client device, Web browser or desktop application will access a distributed GPU cloud. The local host may be one node if it provides the best optimized service if it provides such service.

1.2 Component and work flow
Foaken server side has the following component
- a mini Web server based on NanoHTTPD (Java)
- in-line HTML pages and forms for end-user interaction
- functionality to verify Facebook Access Token using HTTPS-GET
- functionality of basic Facebook graph API using RestFB
The client side, not part of Foaken, requires a Web browser support Javascript, HTTPS and Internet connection.
1.2.1 Work flow or use case
- an Web application designer creates a Facebook application, thus acquires the Facebook App ID and Facebook Application Screte
- the Web application (Foaken Java app) is started at local host and ONLY (so far for security reason)
- an end user open a Web browser connect to the local host URL
- the end user interacts with Facebook login interface through a Web browser and gets the access token ( so far authentication failure and end user refusal is not handled at this project) and the tutorial experiemental process continues
- the end user Web is redirected to a URL (still local host ONLY), the Web browser prompts the user to copy/paste and submit the full URL.
It may look out of handy -- the user why not just copy/paste the token directly to a GUI component, a textarea e.g., of the desktop application?
The Web server may capture the referrer URL which contains the access token automatically, but Facebook login interface progresses in HTTPS throughout.
It is a fact that NanoHTTPD so far does not support HTTPS. We thus can not source the referrer URL in the Web server with plain HTTP communication ( no formal references referrable).
- after the user submits the URL string, the Web browser continues and shows the access token is verified from a RestFB example (done at the server side).
- if the developer or user wants to repeat the whole process, the Web server has to be re-started. The developer or user should use the Web browser to re-establish the connection to the new instance of the mini Web server.

1.3 Scope
The program, software, project of concept hereby is aimed to ease the understanding and usage of the up-to-date Facebook API. The audience are supposed to have moderate Web application design and Java programming background.
The program, software, project of concept is not an industrial domain product.
For short, it is an experimental tutorial.

1.4 Security and privacy concern
1.4.1 All Internet network communication is between user host and Facebook using HTTPS. I should notice the readers while writing the first sensence of this paragraph, the RestFB communication is not confirmed as secure layer communication by a network listener (20130827).
1.4.2 There is no guarantee of third party software/source code/library generating network traffic during this tutorial process.
1.4.3 This original application using Facebook Application default scope. The submission of the access token in 1.2.1 grants the original Facebook application (this application you downloaded) with the so called default scope.
1.4.4 Zhikai Wang/www.heteroclinic.net does not directly keep any record or acquire any information of any user who has used this tutorial project utilizing this application.
1.4.5 Zhikai Wang/www.heteroclinic.net may collect information through and only through Facebook Application control panel applied in this tutorial project, so far what is available is ONLY the user list.
