Debian Codegraph @

samples/mandel/README.html

raw
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
2 <!--
3
4 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
5
6 Copyright (c) 2010-2011 Oracle and/or its affiliates. All rights reserved.
7
8 The contents of this file are subject to the terms of either the GNU
9 General Public License Version 2 only ("GPL") or the Common Development
10 and Distribution License("CDDL") (collectively, the "License"). You
11 may not use this file except in compliance with the License. You can
12 obtain a copy of the License at
13 http://glassfish.java.net/public/CDDL+GPL_1_1.html
14 or packager/legal/LICENSE.txt. See the License for the specific
15 language governing permissions and limitations under the License.
16
17 When distributing the software, include this License Header Notice in each
18 file and include the License file at packager/legal/LICENSE.txt.
19
20 GPL Classpath Exception:
21 Oracle designates this particular file as subject to the "Classpath"
22 exception as provided by Oracle in the GPL Version 2 section of the License
23 file that accompanied this code.
24
25 Modifications:
26 If applicable, add the following below the License Header, with the fields
27 enclosed by brackets [] replaced by your own identifying information:
28 "Portions Copyright [year] [name of copyright owner]"
29
30 Contributor(s):
31 If you wish your version of this file to be governed by only the CDDL or
32 only the GPL Version 2, indicate your decision by adding "[Contributor]
33 elects to include this software in this distribution under the [CDDL or GPL
34 Version 2] license." If you don't indicate a single choice of license, a
35 recipient has the option to distribute your version of this file under
36 either the CDDL, the GPL Version 2 or to extend the choice of license to
37 its licensees as provided above. However, if you add GPL Version 2 code
38 and therefore, elected the GPL Version 2 license, then the option applies
39 only if the new code is made subject to such option by the copyright
40 holder.
41
42 -->
43 <html><head><title>Mandel Service Example</title></head>
44
45 <body>
46 <h1>Mandel Service Example</h1>
47 <p>This example demonstrates a service,
48 implemented in <A HREF="http://www.scala-lang.org/">Scala</A>, that
49 calculates the <A HREF="http://en.wikipedia.org/wiki/Mandelbrot_set">Mandelbrot</A>
50 set over a specified area (of the complex plane) and returns an image
51 of that area that represents the set.</p>
52 <h2>Contents</h2>
53 <p>The example consists of one web resource implemented by the
54 following:
55 </p>
56 <dl>
57 <dt><code>mandel.MandelService</code></dt>
58 <dd>This Scala class returns the a PNG image of a Mandelbrot set
59 calculated over a specified area.</dd>
60 </dl>
61 <p>
62 The mapping of the URI path space is presented in the following
63 table:</p>
64 <TABLE WIDTH=419 BORDER=1 CELLPADDING=2 CELLSPACING=3>
65 <COL WIDTH=177>
66 <COL WIDTH=115>
67 <COL WIDTH=102>
68 <TR>
69 <TH WIDTH=177>
70 <P>URI path</TH>
71 <TH WIDTH=115>
72 <P>Resource class</TH>
73 <TH WIDTH=102>
74 <P>HTTP methods</TH>
75 </TR>
76 <TR>
77 <TD WIDTH=177>
78 <P>({lx},{ly}),({ux},{uy})</TD>
79 <TD WIDTH=115>
80 <P>MandelResource</TD>
81 <TD WIDTH=102>
82 <P>GET</TD>
83 </TR>
84 </TABLE>
85 <P>The URI template, &ldquo;({lx},{ly}),({ux},{uy})&rdquo;, embeds
86 the bottom left had corner and the top right hand corner of the area
87 to calculate as template variables. The following query parameters
88 are supported by MandelResource:</P>
89 <TABLE WIDTH=419 BORDER=1 CELLPADDING=2 CELLSPACING=3>
90 <COL WIDTH=127>
91 <COL WIDTH=104>
92 <COL WIDTH=162>
93 <TR>
94 <TH WIDTH=127>
95 <P>Query parameter</TH>
96 <TH WIDTH=104>
97 <P>Default Value</TH>
98 <TH WIDTH=162>
99 <P>Description</TH>
100 </TR>
101 <TR>
102 <TD WIDTH=127>
103 <P>imageSize</TD>
104 <TD WIDTH=104>
105 <P>512</TD>
106 <TD WIDTH=162>
107 <P>The maximum size of the image in width or height</TD>
108 </TR>
109 <TR>
110 <TD WIDTH=127>
111 <P>limit
112 </TD>
113 <TD WIDTH=104>
114 <P>512</TD>
115 <TD WIDTH=162>
116 <P>The limit on the number of iterations to determine if a point
117 on the complex plane belongs to the Mandelbrot set.</TD>
118 </TR>
119 <TR>
120 <TD WIDTH=127>
121 <P>workers</TD>
122 <TD WIDTH=104>
123 <P>8</TD>
124 <TD WIDTH=162>
125 <P>The number of Scala actors instantiated to
126 </TD>
127 </TR>
128 </TABLE>
129 <P>The URI template, &ldquo;({lx},{ly}),({ux},{uy})&rdquo;, embeds
130 the bottom left had corner and the top right hand corner of the area
131 to calculate.</P>
132 <H2>Scaling up</H2>
133 <P>The implementation utilizes Scala actors to calculate the set
134 concurrently. If a system can avail of many hardware threads of
135 multiple cores in a single chip then the Mandelbrot set can be
136 calculated in parallel. The number of concurrent actors can be
137 modified by the query parameter &ldquo;workers&rdquo;. Such a
138 parameter should not really be required as Scala's event-based actors
139 are cheap to construct and in theory the runtime should utilize has
140 many threads as the hardware and configuration allows to concurrently
141 process actors. However, it is useful for testing and verifying
142 performance increases (yet to be verified with this implementation!).</P>
143 <h2>Running the Example</h2>
144 <P>Run the example as follows:</P>
145 <dl>
146 <dd><pre>
147 mvn clean compile exec:java</pre></dd></dl>
148 <p>
149 then go to the URL
150 <a href="http://localhost:9998/mandelbrot/(-2.2,-1.2),(0.8,1.2)">http://localhost:9998/mandelbrot/(-2.2,-1.2),(0.8,1.2)</a>.</p>
151 <h2>TODO</h2>
152 <ul>
153 <li><p>Test on multi-core machine to see if performance is improved.</p>
154 <li><p>Assign Etags based on the area to calculate the image size
155 and the limit.</p>
156 <li><p>A client that enables one to zoom into the set</p>
157 <li><p>A client that enables one to browse the set a bit like the
158 way Google maps works. This would be an example of scaling out.</p>
159 </ul>
160 </body>
161 </html>