source: subversion/applications/rendering/tilesAtHome/lib/Request.pm @ 11553

Last change on this file since 11553 was 11110, checked in by matthiasj, 11 years ago

move all *.pm files into lib and add lib to the library search paths

File size: 7.1 KB
Line 
1# A 'Request' encapsulates a render request.
2=pod
3
4=head1 Request for a t@h render
5
6=head2 License and authors
7
8 # Copyright 2008, by Sebastian Spaeth
9 # licensed under the GPL v2 or (at your option) any later version.
10
11=head2 Overview
12
13The I<Request> object encapsulates a render request from the t@h server. It is used to fetch a request from the server and contains all the contect information of the request that we have. It is then handed a render method that processes it. I<Request> can also return the request back to the server in case of an error. It encapsulates all the request-related communication with the server (except for uploading the resulting files).
14
15=cut
16
17#see rest of the pd documentation is at the end of this file. Please keep
18# the description of public methofs/attributes up to date
19package Request;
20
21use warnings;
22use strict;
23use LWP::UserAgent;
24use Error qw(:try);
25use tahlib;
26use TahConf;
27
28#unrenderable is a class global hash that keeps unrenderable tilesets as ['z x y']=1
29our %unrenderable = ();
30
31#-----------------------------------------------------------------------------
32# Request can be instantiated with ->new(Z,X,Y), alternatively set those with ->ZXY(z,x,y) later.
33# e.g. my $r = new Request or my $r = Request->new()
34#-----------------------------------------------------------------------------
35sub new 
36{
37    my $class = shift;
38    my $self = {
39        MIN_Z => undef,
40        X => undef,
41        Y  => undef,
42        lastModified => 0,  #unix timestamp of file on server
43        complexity => 0,    #byte size of file on server
44        layers => [],
45        Config => TahConf->getConfig(),
46    };
47    bless $self, $class;
48    $self->ZXY(@_);
49    return $self;
50}
51
52#-----------------------------------------------------------------------------
53# set and/or retrieve the z,x,y of a request
54#-----------------------------------------------------------------------------
55sub ZXY
56{
57    my $self = shift;
58    my ($new_z, $new_x, $new_y) = @_;
59
60    if (defined($new_z) and defined($new_x) and defined($new_y)) {
61        my $maxCoords = (2 ** $new_z - 1);
62        if (($new_x < 0) or ($new_x > $maxCoords) or ($new_y < 0) or ($new_y > $maxCoords)) {
63            throw RequestError "Coordinates ($new_x, $new_y) out of bounds (0..$maxCoords) for zoom $new_z";
64        }
65        $self->{MIN_Z} = $new_z;
66        $self->{X} = $new_x;
67        $self->{Y} = $new_y;
68    }
69
70    return ($self->Z($new_z),$self->X($new_x),$self->Y($new_y))
71}
72
73#-----------------------------------------------------------------------------
74# retrieve (read-only) the z,x,y as string in form 'z,x,y'
75#-----------------------------------------------------------------------------
76sub ZXY_str
77{
78    my $self = shift;
79    return $self->Z.','.$self->X.','.$self->Y;
80}
81
82#-----------------------------------------------------------------------------
83# retrieve (read-only) the zoom level of a request
84#-----------------------------------------------------------------------------
85sub Z
86{
87    my $self = shift;
88    return $self->{MIN_Z}
89}
90
91#-----------------------------------------------------------------------------
92# retrieve (read-only) the x coordinate of a request
93#-----------------------------------------------------------------------------
94sub X
95{
96    my $self = shift;
97    return $self->{X}
98}
99
100#-----------------------------------------------------------------------------
101# retrieve (read-only) the y coordinate of a request
102#-----------------------------------------------------------------------------
103sub Y
104{
105    my $self = shift;
106    return $self->{Y}
107}
108
109#-----------------------------------------------------------------------------
110# set and/or retrieve the required layers of a request
111# it's handed an array of layers when setting, eg.
112# $r->layers('tile', 'maplint')
113# returns an array of layernames when reading (empty array if unset)
114#-----------------------------------------------------------------------------
115sub layers
116{
117    my $self = shift;
118    my @layers = @_;
119    if (@layers) {
120        @{$self->{layers}} =  @layers;
121    }
122    return @{$self->{layers}};
123}
124
125
126#-----------------------------------------------------------------------------
127# Set or retrieve the required layers of a request
128# usage, e.g. $r->layers_str([$layers_string])
129# returns comma separated string of layers, eg. 'tile,maplint'
130# returns empty string '' if unset.
131#-----------------------------------------------------------------------------
132sub layers_str
133{
134    my $self = shift;
135    my $layers_str = shift;
136    if (defined $layers_str) {
137        @{$self->{layers}} =  split(/,/,$layers_str);
138    }
139    return join(",", @{$self->{layers}});
140}
141
142
143#-----------------------------------------------------------------------------
144# set and/or retrieve the last modified timestamp of a request
145#-----------------------------------------------------------------------------
146sub lastModified
147{
148    my $self = shift;
149    my $time = shift;
150    if (defined($time)) {
151        $self->{lastModified} = $time;
152    }
153    return $self->{lastModified}
154}
155
156#-----------------------------------------------------------------------------
157# set and/or retrieve the complexity of a request
158#-----------------------------------------------------------------------------
159sub complexity
160{
161    my $self = shift;
162    my $complexity = shift;
163    if (defined($complexity)) {
164        $self->{complexity} = $complexity;
165    }
166    return $self->{complexity}
167}
168
169#-----------------------------------------------------------------------------
170# get/set the unrenderable status of a tileset
171# takes 1 as parameter if setting as unrenderable
172# without parrameters returns the unrenderable status
173# currently does not check that ZXY are initialized.
174#-----------------------------------------------------------------------------
175sub is_unrenderable
176{
177    my $self = shift;
178    # TODO check that XYZ are initialized
179    my $zxy= $self->Z.' '.$self->X.' '.$self->Y;
180    $unrenderable{$zxy} = 1 if @_;
181    return $unrenderable{$zxy};
182}
183
184package RequestError;
185use base 'Error::Simple';
186
1871;
188
189=pod
190
191=head2 Public methods
192
193=head3 CREATION & COORDINATES:
194
195=over
196
197=item C<< ->new(Z,X,Y) >> (set)
198
199A I<Request> can be instantiated with ->new(Z,X,Y). Alternatively those coordinates can be set with ->ZXY(z,x,y) later. Of course you don't need to set those coordinates if you plan to retrieve a request from the server.
200
201e.g. my $r = new Request or my $r = Request->new()
202
203=item C<< ->ZXY(z,x,y) >> (set or get)
204
205=item C<< ->ZXY_str >> (read-only) returns 'z,x,y' as string
206
207=item C<< ->X(x) >> (set or get)
208
209=item C<< ->Y(y) >> (set or get)
210
211=item C<< ->Z(z) >> (set or get)
212
213=item C<< ->layers(@layers) >> (set or get)
214
215Sets and returns array of layernames
216
217=item C<< ->layers_str() >> (set or get)
218
219Sets and returns comma-separated layer string
220
221=item C<< ->lastModified([$timestamp]) >> (set or get)
222
223Sets and returns unix timestamp of the tileset file on server. The server
224responds with  0 if it doesn't have the tileset yet. Although nothing prevents
225you technically from setting this attribute it only makes sense to use it for
226reading.
227
228=item C<< ->complexity([$complexity]) >> (set or get)
229
230Sets and returns the byte size of the tileset file on the server. It will be set
231to 0 if the server does not have the tileset yet.
232
233=back
234
235=cut
Note: See TracBrowser for help on using the repository browser.