code.grnet.gr Git - pithos-web-client/blob - docs/source/webclient.rst

   1 Pithos+ Web Client
   2 ==================
   3
   4 Introduction
   5 ------------
   6
   7 Document Revisions
   8 ^^^^^^^^^^^^^^^^^^
   9
  10 =====================  =====================================
  11 Revision               Description
  12 =====================  =====================================
  13 0.1 (Apr 09, 2012)     Initial release.
  14 =====================  =====================================
  15
  16 Build instructions
  17 ------------------
  18 prerequisites: git, jdk 1.6, ant
  19
  20 First get the source from the git repository
  21
  22 git clone https://code.grnet.gr/git/pithos-web-client
  23
  24 cd pithos-web-client
  25
  26 Edit the file runtime.properties and set the loginUrl and cloudbar properties to the correct values eg.
  27
  28 loginUrl=https://accounts.staging.okeanos.grnet.gr/im/login?next=https%3A//pithos.staging.okeanos.grnet.gr/ui
  29
  30 CLOUDBAR_ACTIVE_SERVICE = cloud;
  31
  32 CLOUDBAR_LOCATION = https://accounts.staging.okeanos.grnet.gr/static/im/cloudbar/
  33
  34 CLOUDBAR_SERVICES = https://accounts.staging.okeanos.grnet.gr/im/get_services
  35
  36 CLOUDBAR_MENU = https://accounts.staging.okeanos.grnet.gr/im/get_menu
  37
  38 Then run ant
  39
  40 ant
  41
  42 cd bin/www/gr.grnet.pithos.web.Pithos
  43
  44 This folder contains the "binaries" (html and javascript actually). Those files should be put somewhere to be served by the web server.
  45 For deploying to pithos.dev.grnet.gr, upload everything to /var/www/pithos_web_client where they are served under /ui.
  46
  47 Important reminder: Due to Same-Origin-Policy the web client should be served under the same domain as the API.
  48
  49 Technology and tools
  50 --------------------
  51 Pithos+ web client is a gwt application. It is written in Java and compiled to javascript that runs in the browser. More info about gwt can be found here http://developers.google.com/web-toolkit/
  52
  53 General architecture
  54 --------------------
  55
  56 The web client does an adaptation of the container/object server-side data model to the more user-friendly folder/file data model. The client uses the API to retrieve info about the containers and objects from the server and displays them in a tree-like structure. It uses two special gwt widgets, CellTree (https://developers.google.com/web-toolkit/doc/latest/DevGuideUiCellWidgets#celltree) and CellTable (https://developers.google.com/web-toolkit/doc/latest/DevGuideUiCellTable) for the folder tree and filelist accordingly. The CellTree widget initiates calls to the API at the beginning and each time a subtree is expanded in order to fetch all info needed to display the subfolders. That way the datamodel is controlled by the widget.
  57
  58 Authentication
  59 --------------
  60
  61 Authentication is provided by an external service. Upon loading the web client checks for the existence of the authentication cookie named '_pithos2_a'. If the cookie is present then it is parsed for the username and authentication token. The format of the cookie content is
  62
  63 username|token
  64
  65 These username and token are used for every request to the server. If at any time, the client receives an HTTP 401 (Unauthorized) which means that the token has expired, then the user is informed and redirected to the login page.
  66
  67 If the auth cookie is not present in the first place then the user is immediately redirected to the login page.
  68
  69 The login page url is defined in the runtime.properties file and it must end with a 'next=' url parameter. The value of the parameter will be determined automatically. If the parameter is not present then the login page will not be able to redirect back to the client after a successful login and the use will end up at her profile page.
  70
  71 API Usage
  72 ---------
  73
  74 Initialization
  75 ^^^^^^^^^^^^^^
  76 Upon loading, the web client performs the following steps:
  77
  78 Ckeck if the user is authenticated (auth cookie present)
  79
  80 The application page is constructed
  81
  82 Requests the server for the user account and files. This is done in various stages. First a request is made for the user account data
  83
  84 GET /v1/username?format=json
  85
  86 If there is a container named 'pithos' and a container named 'trash' then it proceeds to the folder tree construction. Otherwise the missing containers will be created with a request
  87
  88 PUT /v1/username/pithos
  89
  90 PUT /v1/username/trash
  91
  92 Constructing the folder tree
  93 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  94 The folder tree displays in a tree structure all the user 's containers (including trash). For each container a request is made
  95
  96 GET /v1/username/pithos?format=json&delimiter=/&prefix=
  97
  98 to get the first level of folders (either actual objects with application/folder content type or virtual prefixes). The home folder (pithos) is always displayed first, selected and expanded and the trash container is always last.
  99
 100 Due to the pithos container being programmatically selected and expanded at the beginning, additional requests
 101
 102 GET /v1/username/pithos?format=json&delimiter=/&prefix=pithos_subfolder1
 103
 104 are made to server to fetch details of the subfolders. We need to know if a subfolder has its own subfolders so that we display the cross sign next to it.
 105
 106 Constructing the "Shared by me" tree
 107 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 108 My shared tree construction is a bit more complicated. All files that are shared individualy (not through sharing their parent folder) are displayed directly in the root of the tree (inside the 'Shared by me' folder).
 109
 110 All shared folders are displayed in tree structure under the root.
 111
 112 The above means that the client has to make a series of requests to collect all shared items and display them accordingly.
 113
 114 First a
 115
 116 GET /v1/username/container?format=json&delimiter=/&prefix=
 117
 118 is made for each container. If the container is shared it is added to the tree (under "Shared by me") and the client continues to the next container (this has to be re-visited because it was based that due to the permission inheritance the subfolders are also shared. Since the inheritance has been removed this is no longer valid).
 119
 120 If the container is not shared we have to go deeper to find possible shared subfolders and files. So we examine each file in the folder and if shared we add it in the "Shared by me" folder and we also do a nested iteration getting each subfolder
 121
 122 GET /v1/username/container?format=json&delimiter=/&prefix=subfolder
 123
 124 and this is done recursively until all shared folders have been collected.
 125
 126 Constructing the "Shared by others" tree
 127 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 128 The "Shared by others" tree has the additional complication that we need to get the users that share objects with us and display them as a first level of subfolders.
 129
 130 GET /v1?format=json
 131
 132 For each of the users we do an additional
 133
 134 GET /v1/username?format=json
 135
 136 to get the containers shared by the user and for each container we do the same sequence of requests as in the "Shared by me case". The difference no is that we don't need to check if the container/folder/file is shared because all requests with a different username always return only object that are visible to the logged-on user.
 137
 138 Constructing the Groups tree
 139 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 140
 141 The groups tree is contructed with the initial request for the user account data which returns the groups defined be the user along with their members.
 142
 143 File sharing
 144 ^^^^^^^^^^^^
 145
 146 File uploading
 147 ^^^^^^^^^^^^^^
 148 File uploading is done using the plupload http://www.plupload.com/ plugin.
 149
 150 File Copy/Cut/Paste operations
 151 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^