File: PageCompilerUserGuide.html

package info (click to toggle)
poco-doc 1.3.6-1
  • links: PTS
  • area: main
  • in suites: buster, jessie, jessie-kfreebsd, squeeze, stretch, wheezy
  • size: 10,076 kB
  • ctags: 9,611
  • sloc: makefile: 31
file content (308 lines) | stat: -rw-r--r-- 16,649 bytes parent folder | download | duplicates (2)
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
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>POCO C++ Server Page Compiler User Guide</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<meta name="author" content="Applied Informatics Software Engineering GmbH and Contributors"/>
<meta name="publisher" content="Applied Informatics Software Engineering GmbH and Contributors"/>
<meta name="copyright" content="Copyright (c) 2009, Applied Informatics Software Engineering GmbH and Contributors"/>
<meta name="language" content="en"/>
<meta name="date" content="2009-11-24"/>
<meta name="generator" content="PocoDoc"/>
<link rel="stylesheet" href="css/styles.css" type="text/css"/>
</head>
<body bgcolor="#ffffff" leftmargin="0" topmargin="0">
<div class="header">
<h1 class="category">POCO PageCompiler</h1>
<h1 class="title">POCO C++ Server Page Compiler User Guide</h1>
</div>
<div class="body">
<h2>Contents</h2>
<div class="toc"><ul>
<li class="level1"><a href="#0">Introduction</a></li>
<li class="level1"><a href="#1">C++ Server Page Syntax</a></li>
<li class="level2"><a href="#2">Hidden Comment</a></li>
<li class="level2"><a href="#3">Implementation Declaration</a></li>
<li class="level2"><a href="#4">Header Declaration</a></li>
<li class="level2"><a href="#5">Expression</a></li>
<li class="level2"><a href="#6">Scriptlet</a></li>
<li class="level2"><a href="#7">Pre-Response Scriptlet</a></li>
<li class="level2"><a href="#8">Include Directive</a></li>
<li class="level2"><a href="#9">C++ Header Include Directive</a></li>
<li class="level2"><a href="#10">C++ Implementation Include Directive</a></li>
<li class="level2"><a href="#11">Page Directive</a></li>
<li class="level3"><a href="#12">class</a></li>
<li class="level3"><a href="#13">namespace</a></li>
<li class="level3"><a href="#14">baseClass</a></li>
<li class="level3"><a href="#15">ctorArg</a></li>
<li class="level3"><a href="#16">export</a></li>
<li class="level3"><a href="#17">form</a></li>
<li class="level3"><a href="#18">formPartHandler</a></li>
<li class="level3"><a href="#19">contentType</a></li>
<li class="level3"><a href="#20">chunked</a></li>
<li class="level3"><a href="#21">session (OSP only)</a></li>
<li class="level3"><a href="#22">sessionTimeout (OSP only)</a></li>
<li class="level3"><a href="#23">buffered</a></li>
<li class="level3"><a href="#24">precondition</a></li>
<li class="level2"><a href="#25">Implicit Objects</a></li>
<li class="level3"><a href="#26">request</a></li>
<li class="level3"><a href="#27">response</a></li>
<li class="level3"><a href="#28">responseStream</a></li>
<li class="level3"><a href="#29">form</a></li>
<li class="level3"><a href="#30">session (OSP only)</a></li>
<li class="level1"><a href="#31">Invoking the Page Compiler</a></li>
<li class="level2"><a href="#32">Configuration Properties</a></li>
</ul></div>
<div class="description">
<p></p><h2><a name="0">Introduction</a></h2><p>
PageCompiler is a command line tool that translates HTML files (and other kinds of files) into C++ code, more precisely, subclasses of <a href="Poco.Net.HTTPRequestHandler.html" title="class Poco::Net::HTTPRequestHandler">Poco::Net::HTTPRequestHandler</a>. The source files can contain special directives that allow it to include C++ code into the source file. The syntax of this directives is based on the syntax used for  Java Server Pages (JSP) and Active Server Pages. </p>
<p>The following introductory sample shows the code for a simple page that displays the current date and time. </p>
<p></p>
<pre>&lt;%@ page class=&quot;TimeHandler&quot; %&gt;
&lt;%!
    #include &quot;Poco/DateTime.h&quot;
    #include &quot;Poco/DateTimeFormatter.h&quot;
    #include &quot;Poco/DateTimeFormat.h&quot;


    using Poco::DateTime;
    using Poco::DateTimeFormatter;
    using Poco::DateTimeFormat;
%&gt;

&lt;%
    DateTime now;
    std::string dt(DateTimeFormatter::format(now, DateTimeFormat::SORTABLE_FORMAT));
%&gt;
&lt;html&gt;
&lt;head&gt;
&lt;title&gt;Time Sample&lt;/title&gt;
&lt;/head&gt;
&lt;body&gt;
&lt;h1&gt;Time Sample&lt;/h1&gt;
&lt;p&gt;&lt;%= dt %&gt;&lt;/p&gt;
&lt;/body&gt;
&lt;/html&gt;
</pre>
<p>     </p>
<p>Sending the above code to the page compiler will generate two files, a header file (<tt>TimeHandler.h</tt>) and an implementation file (<tt>TimeHandler.cpp</tt>). The files define a subclass of <a href="Poco.Net.HTTPRequestHandler.html" title="class Poco::Net::HTTPRequestHandler">Poco::Net::HTTPRequestHandler</a> named <tt>TimeHandler</tt>. The generated <tt>handleRequest</tt> member function contains code to send the HTML code contained in the source file to the client, as well as the C++ code fragments found  in between the Scriptlet tags.  </p>
<p></p>
<p></p><h2><a name="1">C++ Server Page Syntax</a></h2><p>
</p>
<p>The following special tags are supported in a C++ server page (CPSP) file. </p>
<p></p><h3><a name="2">Hidden Comment</a></h3><p>
</p>
<p>A hidden comment documents the CPSP file, but is not sent to the client. </p>
<p></p>
<pre>&lt;%-- &lt;comment&gt; --%&gt;
</pre>
<p> </p>
<p></p><h3><a name="3">Implementation Declaration</a></h3><p>
</p>
<p>An implementation declaration is copied to the implementation file immediately after the block containing the standard <tt>#include</tt> directives. It is used to include additional header files and <tt>using</tt> declarations, as well as to define classes needed later on. </p>
<p></p>
<pre>&lt;%!
    &lt;declaration&gt;
    ...
%&gt;
</pre>
<p> </p>
<p></p><h3><a name="4">Header Declaration</a></h3><p>
</p>
<p>A header declaration is copied to the header file immediately after the block containing the standard <tt>#include</tt> directives. It is usually used to include the header file containing the definition of the base class for the request handler, if a custom base class is required. </p>
<p></p>
<pre>&lt;%!!
    &lt;declaration&gt;
    ...
%&gt;
</pre>
<p> </p>
<p></p><h3><a name="5">Expression</a></h3><p>
</p>
<p>The result of any valid C++ expression can be directly inserted into the page, provided the result can be written to an output stream. Note that the expression must not end with a semicolon. </p>
<p></p>
<pre>&lt;%= &lt;expression&gt; %&gt;
</pre>
<p> </p>
<p></p><h3><a name="6">Scriptlet</a></h3><p>
</p>
<p>Arbitrary C++ code fragments can be included using the Scriptlet directive. </p>
<p></p>
<pre>&lt;%
    &lt;statement&gt;
    ...
%&gt;
</pre>
<p> </p>
<p></p><h3><a name="7">Pre-Response Scriptlet</a></h3><p>
</p>
<p>This is similar to an ordinary scriptlet, except that it will be executed before the HTTP response is sent. This can be used to manipulate the HTTP response object. </p>
<p></p>
<pre>&lt;%%
    &lt;statement&gt;
    ...
%&gt;
</pre>
<p>The main feature of this directive is that it allows to send a redirect response to the client if a certain condition is true. </p>
<p>Example: </p>
<pre>&lt;%%
    if (!loggedIn)
    {
    	return response.redirect(&quot;/&quot;);
    }
%&gt;
</pre>
<p></p><h3><a name="8">Include Directive</a></h3><p>
</p>
<p>Another CPSP file can be included into the current file using the Include Directive. </p>
<p></p>
<pre>&lt;%@ include page=&quot;&lt;path&gt;&quot; %&gt;
</pre>
<p> </p>
<p></p><h3><a name="9">C++ Header Include Directive</a></h3><p>
</p>
<p>Include a C++ header file in the generated header file. </p>
<pre>&lt;%@ header include=&quot;&lt;path&gt;&quot; %&gt;
</pre>
<p>This corresponds to: </p>
<pre>&lt;%!! #include &quot;&lt;path&gt;&quot; %&gt;
</pre>
<p>A variant of this directive is: </p>
<pre>&lt;%@ header sinclude=&quot;&lt;path&gt;&quot; %&gt;
</pre>
<p>This corresponds to: </p>
<pre>&lt;%!! #include &lt;&lt;path&gt;&gt; %&gt;

</pre>
<p></p><h3><a name="10">C++ Implementation Include Directive</a></h3><p>
</p>
<p>Include a C++ header file in the generated implementation file. </p>
<pre>&lt;%@ impl include=&quot;&lt;path&gt;&quot; %&gt;
</pre>
<p>This corresponds to: </p>
<pre>&lt;%! #include &quot;&lt;path&gt;&quot; %&gt;
</pre>
<p>A variant of this directive is: </p>
<pre>&lt;%@ impl sinclude=&quot;&lt;path&gt;&quot; %&gt;
</pre>
<p>This corresponds to: </p>
<pre>&lt;%! #include &lt;&lt;path&gt;&gt; %&gt;

</pre>
<p></p><h3><a name="11">Page Directive</a></h3><p>
</p>
<p>The Page Directive allows the definition of attributes that control various aspects of C++ code generation. </p>
<p></p>
<pre>&lt;%@ page &lt;attr&gt;=&quot;&lt;value&gt;&quot; ... %&gt;
</pre>
<p> </p>
<p>The following page attributes are supported: </p>
<p></p><h4><a name="12">class</a></h4><p>
</p>
<p>Specifies the name of the generated class. Defaults to the base name of the source file with the word &quot;Handler&quot; appended. </p>
<p></p><h4><a name="13">namespace</a></h4><p>
</p>
<p>If specified, sets the namespace where the generated classes will be in. No namespace will be used if omitted. </p>
<p></p><h4><a name="14">baseClass</a></h4><p>
</p>
<p>Specifies the name of the class used as the base class for the generated  request handler class. Defaults to <a href="Poco.Net.HTTPRequestHandler.html" title="class Poco::Net::HTTPRequestHandler">Poco::Net::HTTPRequestHandler</a>. Do not forget to add a Header Declaration containing an <tt>#include</tt> directive for the header file containing the definition of that class, otherwise the generated code won't compile. </p>
<p></p><h4><a name="15">ctorArg</a></h4><p>
</p>
<p>Allows to specify the type of a single argument being passed to the constructor of the generated request handler class. Can only be used together with <tt>baseClass</tt>. The argument is passed on to the constructor of the base class, therefore, one of the  constructors of the base class must also accept a single argument of the specified type. </p>
<p></p><h4><a name="16">export</a></h4><p>
</p>
<p>Allows to specify a DLL import/export directive that is being added to the request handler class definition. Useful for exporting a request handler class from a Windows DLL. </p>
<p></p><h4><a name="17">form</a></h4><p>
</p>
<p>Enable or disable automatic form handling. If enabled, which is the default, a <a href="Poco.Net.HTMLForm.html" title="class Poco::Net::HTMLForm">Poco::Net::HTMLForm</a> object is automatically created in the request handler and accessible through a variable named <tt>form</tt>. Set the value to <tt>false</tt> to disable form handling. </p>
<p></p><h4><a name="18">formPartHandler</a></h4><p>
</p>
<p>Allows you to pass a <a href="Poco.Net.PartHandler.html" title="class Poco::Net::PartHandler">Poco::Net::PartHandler</a> object to the form object for  processing file uploads. A subclass of <a href="Poco.Net.PartHandler.html" title="class Poco::Net::PartHandler">Poco::Net::PartHandler</a> must be defined (using an Implementation Declaration), and the constructor of the part  handler must take a (const) reference to the request handler instance as argument. </p>
<p></p><h4><a name="19">contentType</a></h4><p>
</p>
<p>Allows you to specify the MIME content type for the page. Defaults to text/html. </p>
<p></p><h4><a name="20">chunked</a></h4><p>
</p>
<p>Allows you to specify whether the response is sent using chunked transfer encoding. Defaults to <tt>true</tt>. Set the value to <tt>false</tt> to disable chunked transfer encoding. </p>
<p></p><h4><a name="21">session (OSP only)</a></h4><p>
</p>
<p>For use with the POCO Open Service Platform only. </p>
<p>Specifies the identifier of the session obtained from the OSP Web Session Manager. If specified, a Poco::OSP::Web::WebSession object will be available in the request handler through a variable named <tt>session</tt>. The variable is of type Poco::OSP::Web::WebSession::Ptr. </p>
<p></p><h4><a name="22">sessionTimeout (OSP only)</a></h4><p>
</p>
<p>For use with the POCO Open Service Platform only. </p>
<p>Specifies the session timeout in minutes. </p>
<p></p><h4><a name="23">buffered</a></h4><p>
</p>
<p>Enables or disables response buffering. Response buffering is disabled by default. Set to <tt>true</tt> to enable buffering, or to <tt>false</tt> to disable it. If response buffering is enabled, everything written to the response stream is actually written to a string stream (<tt>std::ostringstream</tt>). Sending of the HTTP response back to the client is deferred to  when the page is complete. </p>
<p></p><h4><a name="24">precondition</a></h4><p>
</p>
<p>Allows to specify a C++ boolean expression which will be evaluated before processing of the page begins. If the expression evaluates to false, processing of the page is immediately terminated and no response is sent to the client. </p>
<p>The expression can be a call to a member function defined in the handler base class. If that function returns false, it can send its own response to the client. </p>
<p>Example: </p>
<pre>&lt;%@ page precondition=&quot;checkCredentials(request, response)&quot; %&gt;
</pre>
<p> </p>
<p></p><h3><a name="25">Implicit Objects</a></h3><p>
</p>
<p>The following objects are available in the handler code. </p>
<p></p><h4><a name="26">request</a></h4><p>
</p>
<p>The HTTP request object - an instance of <a href="Poco.Net.HTTPServerRequest.html" title="class Poco::Net::HTTPServerRequest">Poco::Net::HTTPServerRequest</a>. </p>
<p></p><h4><a name="27">response</a></h4><p>
</p>
<p>The HTTP response object - an instance of <a href="Poco.Net.HTTPServerRequest.html" title="class Poco::Net::HTTPServerRequest">Poco::Net::HTTPServerRequest</a>. </p>
<p></p><h4><a name="28">responseStream</a></h4><p>
</p>
<p>The output stream where the response body is written to. </p>
<p></p><h4><a name="29">form</a></h4><p>
</p>
<p>An instance of <a href="Poco.Net.HTMLForm.html" title="class Poco::Net::HTMLForm">Poco::Net::HTMLForm</a> for processing form arguments. Only available if form processing has not been disabled by setting the <tt>form</tt> page attribute to <tt>false</tt>. </p>
<p></p><h4><a name="30">session (OSP only)</a></h4><p>
</p>
<p>An instance of Poco::OSP::Web::WebSession::Ptr for accessing the Poco::OSP::Web::WebSession object for the current session. Only available with the POCO Open Service Platform, and if the <tt>session</tt> page attribute has been specified. </p>
<p></p>
<p></p><h2><a name="31">Invoking the Page Compiler</a></h2><p>
</p>
<p>The Page Compiler is invoked from the command line. The file names of the CPSP files to be compiled are specified as arguments. </p>
<p>A number of options control the code generation. Options are specified using the usual command-line option syntax for the current operating system (e.g., <tt>/help</tt> on Windows, <tt>--help</tt> or <tt>-h</tt> on Unix). </p>
<p></p>
<ul>
<li>help (h): display usage information </li>
<li>define (D): define a configuration property </li>
<li>config-file (f): load configuration properties from a file </li>
<li>osp (O): add factory class definition/implementation for use with OSP </li>
<li>apache (A): add factory class definition/implementation and shared library manifest for use with ApacheConnector </li>
</ul>
<p></p><h3><a name="32">Configuration Properties</a></h3><p>
</p>
<p>The Page Compiler supports one configuration property, named <tt>PageCompiler.fileHeader</tt>, to optionally specify a header that is  included in every generated file. </p>
<p>The file header can contain references to other configuration properties, using the usual property syntax: <tt>${property}</tt>. </p>
<p>For example, invoking the Page Compiler with the following configuration file: </p>
<p></p>
<pre>PageCompiler.fileHeader = //\n// ${outputFileName}\n//\n
</pre>
<p> </p>
<p>places the following header at the beginning of each generated file (<tt>&lt;filename&gt;</tt> is replaced with the actual name of the file): </p>
<p></p>
<pre>//
// &lt;filename&gt;
//
</pre>
<p> </p>
<p>The following pre-defined properties can be used in the file header: </p>
<p></p>
<ul>
<li><tt>${inputFileName}</tt>: the name of the input file (with directories removed) </li>
<li><tt>${inputFilePath}</tt>: the complete path of the input file </li>
<li><tt>${dateTime}</tt>: the current date and time (YYYY-MM-DD HH:MM:SS) </li>
<li><tt>${outputFileName}</tt>: the name of the current output file (header or implementation file), with directories removed </li>
<li><tt>${outputFilePath}</tt>: the complete path of the current output file </li>
</ul>
<p></p>
<p></p>
</div>
<p class="footer">POCO C++ Libraries 1.3.6-all<br />
Copyright &copy; 2009, <a href="http://pocoproject.org/" target="_blank">Applied Informatics Software Engineering GmbH and Contributors</a></p>
</body>
</html>