1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
|
<html><head>
<meta http-equiv="Pragma" content="no-cache"/>
<meta http-equiv="Cache-Control" content="no-cache"/>
<meta http-equiv="Expires" content="0" />
<title>PyMOL Web Services</title>
</head>
<body>
<h3>Content and Scripting: Same-origin versus multi-origin (cross-domain)</h3>
<p>
For simple HTTP requests, it does not matter whether your web pages
come from the PyMOL server or from another server at your site. So if
you are using PyMOL web applications that contain only simple HTTP
requests, or if you do not need to get results back from PyMOL, then
this same-origin (same-origin) versus multi-origin issue will not affect you.
</p>
<p>However, if you need to get results back from PyMOL, typically via
AJAX and API requests, then there are some limitations. For security
reasons, most (if not all) modern browsers do not allow content
from one server to interact with content from another server. For
AJAX and API requests, this Same-Origin Policy (SOP) requires some attention.</p>
<p>If you want to develop more interactive PyMOL web applications that make use of
results from PyMOL, this document will give you some background on how to do this
using a central web server to serve the application.
<p><b>Same-origin Policy</b> </p>
<p>
Web pages routinely contain links to resources
(html documents, images, javascript, web-services, etc.)
from the same server as well as links to resources from remote servers located anywhere on the web.
While a single web page may even be composed of resources from various servers (sometimes called
a mashup), JavaScript code from one server is not allowed to interact with
resources from a different server.
This <a href="http://en.wikipedia.org/wiki/Same_origin_policy" target=_blank>
SOP</a>
is inherent in most (if not all) modern browsers.
<blockquote>
"Simply stated, the SOP states that JavaScript code running on a web page may not interact with any resource not originating from the same web site. The reason this security policy exists is to prevent malicious web coders from creating pages that steal web users' information or compromise their privacy. While very necessary, this policy also has the side effect of making web developers' lives difficult."
</blockquote>
</p>
<p><b>Same-origin PyMOL web applications</b></p>
<p>
Since PyMOL and its web server are running on the user's desktop (localhost), a
same-origin PyMOL web application would also be run on the desktop. This can be
accomplished by writing a web application (html files and associated JavaScript)
and placing them in a folder accessible by the PyMOL server.
The first seven
<a href="../index.html#sample01" target="_blank"> sample applications</a>
are implemented like this, residing in folders at
<code>$PYMOL_PATH/modules/web/examples/sample[0-7]</code> There
may be future PyMOL web applications delivered with new versions of
PyMOL. Of course, you are free to write your own PyMOL web
applications and store them on each user's machine, or perhaps on a
central file server accessible to each user's machine.
</p>
<p><b>Multi-origin PyMOL web applications</b><p>
<p>
You can also develop PyMOL web applications that reside on a central server at
your site.
The application will be started by loading a web page from that server.
The links, AJAX requests or API requests on that page will send requests to
PyMOL running on the user's desktop (localhost). PyMOL will execute the command
and send back a result. That result can be displayed in a
FRAME, ignored, or used by the JavaScript in your application.
However, for PyMOL web applications that come from another server,
a JavaScript callback approach is necessary to conform to the SOP.
Several <a href="../index.html#sample11" target="_blank">sample applications</a>
illustrate this multi-origin approach.
</p>
<p><b>Information flow and JavaScript callbacks</b></p>
<p>
The basic function of an HTTP server is to listen for requests (GET/URL requests
and POST/FORM requests) and send back HTML documents, images, etc.
These documents are rendered by the browser, typically on a new page or tab or into
an existing FRAME. Using AJAX, it is possible to process the "documents" using
JavaScript, possibly causing the web page to change dynamically instead of refreshing
completely. While the "A" in AJAX stands for asynchronous, it is possible to use
the AJAX's underlying JavaScript XMLHTTPRequest synchronously, but only when
the JavaScript issuing the XMLHTTPRequest originates from the same server to which
the XMLHTTPRequest is being made (same-origin). A synchronous request means that
the XMLHTTPRequest will not return until the server has answered the request.
An asynchronous request means that the call to XMLHTTPRequest will send
the request to the server and return immediately, before the request is answered. The document
or information from the server can be processed by a callback function supplied to
the XMLHTTPRequest or simply ignored.
If you are using AJAX directly, or through
<a href="http://jquery.com/" target="_blank"> JQuery</a> or another JavaScript library, you
should be familiar with the callback mechanism.
<p>
The PyMOL JavaScript API uses XMLHTTPRequest in either synchronous or ansynchronous mode.
Synchronous mode can only be effectively used for same-origin web applications.
Asynchronous mode with callbacks can be used for same-origin or multi-origin
web applications.
</p>
<p>Same-origin advantages</p><ul>
<li>No need to explicitly include host and port in URL links.</li>
<li>PyMOL results can be handled synchronously in JavaScript using
simpler programming techniques and avoiding callbacks.</li>
</ul>
<p>Same-origin disadvantages</p><ul>
<li>Application content must be served up from the local machine (localhost).</li>
</ul>
<p>Multi-origin advantages</p><ul>
<li>Allows development of PyMOL web applications maintained and run from one central server.</li>
<li>No need to update files on users' machines when web application is updated.</li>
</ul>
<p>Multi-origin disadvantages</p><ul>
<li>Must explicitly include the hostname (localhost) and port number in URL links.</li>
<li>PyMOL results must be handled asynchronously in JavaScript using callbacks.</li>
<li>The execution order of pending requests is random on certain browers (e.g. IE6).</li>
</ul>
</body>
</html>
|
