1
|
|
|
<?php |
2
|
|
|
|
3
|
|
|
/* |
4
|
|
|
* This file is part of the php-phantomjs. |
5
|
|
|
* |
6
|
|
|
* For the full copyright and license information, please view the LICENSE |
7
|
|
|
* file that was distributed with this source code. |
8
|
|
|
*/ |
9
|
|
|
namespace JonnyW\PhantomJs\Tests\Unit\Http; |
10
|
|
|
|
11
|
|
|
use JonnyW\PhantomJs\Http\CaptureRequest; |
12
|
|
|
use JonnyW\PhantomJs\Http\RequestInterface; |
13
|
|
|
|
14
|
|
|
/** |
15
|
|
|
* PHP PhantomJs |
16
|
|
|
* |
17
|
|
|
* @author Jon Wenmoth <[email protected]> |
18
|
|
|
*/ |
19
|
|
|
class CaptureRequestTest extends \PHPUnit_Framework_TestCase |
20
|
|
|
{ |
21
|
|
|
|
22
|
|
|
/** +++++++++++++++++++++++++++++++++++ **/ |
23
|
|
|
/** ++++++++++++++ TESTS ++++++++++++++ **/ |
24
|
|
|
/** +++++++++++++++++++++++++++++++++++ **/ |
25
|
|
|
|
26
|
|
|
/** |
27
|
|
|
* Test capture type is returned by default |
28
|
|
|
* if no type is set. |
29
|
|
|
* |
30
|
|
|
* @access public |
31
|
|
|
* @return void |
32
|
|
|
*/ |
33
|
|
|
public function testCaptureTypeIsReturnedByDefaultIfNotTypeIsSet() |
34
|
|
|
{ |
35
|
|
|
$captureRequest = $this->getCaptureRequest(); |
36
|
|
|
|
37
|
|
|
$this->assertSame(RequestInterface::REQUEST_TYPE_CAPTURE, $captureRequest->getType()); |
38
|
|
|
} |
39
|
|
|
|
40
|
|
|
/** |
41
|
|
|
* Test custom type can be set. |
42
|
|
|
* |
43
|
|
|
* @access public |
44
|
|
|
* @return void |
45
|
|
|
*/ |
46
|
|
|
public function testCustomTypeCanBeSet() |
47
|
|
|
{ |
48
|
|
|
$requestType = 'testType'; |
49
|
|
|
|
50
|
|
|
$captureRequest = $this->getCaptureRequest(); |
51
|
|
|
$captureRequest->setType($requestType); |
52
|
|
|
|
53
|
|
|
$this->assertSame($requestType, $captureRequest->getType()); |
54
|
|
|
} |
55
|
|
|
|
56
|
|
|
/** |
57
|
|
|
* Test URL can be set via constructor. |
58
|
|
|
* |
59
|
|
|
* @access public |
60
|
|
|
* @return void |
61
|
|
|
*/ |
62
|
|
|
public function testUrlCanBeSetViaConstructor() |
63
|
|
|
{ |
64
|
|
|
$url = 'http://test.com'; |
65
|
|
|
$captureRequest = $this->getCaptureRequest($url); |
66
|
|
|
|
67
|
|
|
$this->assertSame($url, $captureRequest->getUrl()); |
68
|
|
|
} |
69
|
|
|
|
70
|
|
|
/** |
71
|
|
|
* Test method can be set via constructor. |
72
|
|
|
* |
73
|
|
|
* @access public |
74
|
|
|
* @return void |
75
|
|
|
*/ |
76
|
|
|
public function testMethodCanBeSetViaConstructor() |
77
|
|
|
{ |
78
|
|
|
$method = 'GET'; |
79
|
|
|
$captureRequest = $this->getCaptureRequest(null, $method); |
80
|
|
|
|
81
|
|
|
$this->assertSame($method, $captureRequest->getMethod()); |
82
|
|
|
} |
83
|
|
|
|
84
|
|
|
/** |
85
|
|
|
* Test timeout can be set via constructor. |
86
|
|
|
* |
87
|
|
|
* @access public |
88
|
|
|
* @return void |
89
|
|
|
*/ |
90
|
|
|
public function testTimeoutCanBeSetViaConstructor() |
91
|
|
|
{ |
92
|
|
|
$timeout = 100000; |
93
|
|
|
$captureRequest = $this->getCaptureRequest('http://test.com', 'GET', $timeout); |
94
|
|
|
|
95
|
|
|
$this->assertSame($timeout, $captureRequest->getTimeout()); |
96
|
|
|
} |
97
|
|
|
|
98
|
|
|
/** |
99
|
|
|
* Test invalid method is thrown if method |
100
|
|
|
* is invalid. |
101
|
|
|
* |
102
|
|
|
* @access public |
103
|
|
|
* @return void |
104
|
|
|
*/ |
105
|
|
|
public function testInvalidMethodIsThrownIfMethodIsInvalid() |
106
|
|
|
{ |
107
|
|
|
$this->setExpectedException('\JonnyW\PhantomJs\Exception\InvalidMethodException'); |
|
|
|
|
108
|
|
|
|
109
|
|
|
$captureRequest = $this->getCaptureRequest(); |
110
|
|
|
$captureRequest->setMethod('INVALID_METHOD'); |
111
|
|
|
} |
112
|
|
|
|
113
|
|
|
/** |
114
|
|
|
* Test rect width can be set. |
115
|
|
|
* |
116
|
|
|
* @access public |
117
|
|
|
* @return void |
118
|
|
|
*/ |
119
|
|
|
public function testRectWidthCanBeSet() |
120
|
|
|
{ |
121
|
|
|
$width = 100; |
122
|
|
|
$height = 200; |
123
|
|
|
|
124
|
|
|
$captureRequest = $this->getCaptureRequest(); |
125
|
|
|
$captureRequest->setCaptureDimensions($width, $height); |
126
|
|
|
|
127
|
|
|
$this->assertSame($width, $captureRequest->getRectWidth()); |
128
|
|
|
} |
129
|
|
|
|
130
|
|
|
/** |
131
|
|
|
* Test rect height can be set. |
132
|
|
|
* |
133
|
|
|
* @access public |
134
|
|
|
* @return void |
135
|
|
|
*/ |
136
|
|
|
public function testRectHeightCanBeSet() |
137
|
|
|
{ |
138
|
|
|
$width = 100; |
139
|
|
|
$height = 200; |
140
|
|
|
|
141
|
|
|
$captureRequest = $this->getCaptureRequest(); |
142
|
|
|
$captureRequest->setCaptureDimensions($width, $height); |
143
|
|
|
|
144
|
|
|
$this->assertSame($height, $captureRequest->getRectHeight()); |
145
|
|
|
} |
146
|
|
|
|
147
|
|
|
/** |
148
|
|
|
* Test rect top can be set. |
149
|
|
|
* |
150
|
|
|
* @access public |
151
|
|
|
* @return void |
152
|
|
|
*/ |
153
|
|
|
public function testRectTopCanBeSet() |
154
|
|
|
{ |
155
|
|
|
$width = 100; |
156
|
|
|
$height = 200; |
157
|
|
|
$top = 50; |
158
|
|
|
|
159
|
|
|
$captureRequest = $this->getCaptureRequest(); |
160
|
|
|
$captureRequest->setCaptureDimensions($width, $height, $top); |
161
|
|
|
|
162
|
|
|
$this->assertSame($top, $captureRequest->getRectTop()); |
163
|
|
|
} |
164
|
|
|
|
165
|
|
|
/** |
166
|
|
|
* Test rect left can be set. |
167
|
|
|
* |
168
|
|
|
* @access public |
169
|
|
|
* @return void |
170
|
|
|
*/ |
171
|
|
|
public function testRectLeftCanBeSet() |
172
|
|
|
{ |
173
|
|
|
$width = 100; |
174
|
|
|
$height = 200; |
175
|
|
|
$left = 50; |
176
|
|
|
|
177
|
|
|
$captureRequest = $this->getCaptureRequest(); |
178
|
|
|
$captureRequest->setCaptureDimensions($width, $height, 0, $left); |
179
|
|
|
|
180
|
|
|
$this->assertSame($left, $captureRequest->getRectLeft()); |
181
|
|
|
} |
182
|
|
|
|
183
|
|
|
/** |
184
|
|
|
* Test URL does not contain query params if |
185
|
|
|
* mehtod is not HEAD or GET. |
186
|
|
|
* |
187
|
|
|
* @access public |
188
|
|
|
* @return void |
189
|
|
|
*/ |
190
|
|
|
public function testUrlDoesNotContainQueryParamsIfMethodIsNotHeadOrGet() |
191
|
|
|
{ |
192
|
|
|
$url = 'http://test.com'; |
193
|
|
|
|
194
|
|
|
$data = array( |
195
|
|
|
'test_param1' => 'Testing1', |
196
|
|
|
'test_param2' => 'Testing2' |
197
|
|
|
); |
198
|
|
|
|
199
|
|
|
$captureRequest = $this->getCaptureRequest(); |
200
|
|
|
$captureRequest->setMethod('POST'); |
201
|
|
|
$captureRequest->setUrl($url); |
202
|
|
|
$captureRequest->setRequestData($data); |
203
|
|
|
|
204
|
|
|
$this->assertSame($url, $captureRequest->getUrl()); |
205
|
|
|
} |
206
|
|
|
|
207
|
|
|
/** |
208
|
|
|
* Test URL does contain query params if mehthod |
209
|
|
|
* is GET. |
210
|
|
|
* |
211
|
|
|
* @access public |
212
|
|
|
* @return void |
213
|
|
|
*/ |
214
|
|
|
public function testUrlDoesContainQueryParamsIfMethodIsGet() |
215
|
|
|
{ |
216
|
|
|
$url = 'http://test.com'; |
217
|
|
|
|
218
|
|
|
$data = array( |
219
|
|
|
'test_param1' => 'Testing1', |
220
|
|
|
'test_param2' => 'Testing2' |
221
|
|
|
); |
222
|
|
|
|
223
|
|
|
$captureRequest = $this->getCaptureRequest(); |
224
|
|
|
$captureRequest->setMethod('GET'); |
225
|
|
|
$captureRequest->setUrl($url); |
226
|
|
|
$captureRequest->setRequestData($data); |
227
|
|
|
|
228
|
|
|
$expectedUrl = $url . '?test_param1=Testing1&test_param2=Testing2'; |
229
|
|
|
|
230
|
|
|
$this->assertSame($expectedUrl, $captureRequest->getUrl()); |
231
|
|
|
} |
232
|
|
|
|
233
|
|
|
/** |
234
|
|
|
* Test URL does contain query params if method |
235
|
|
|
* is HEAD. |
236
|
|
|
* |
237
|
|
|
* @access public |
238
|
|
|
* @return void |
239
|
|
|
*/ |
240
|
|
|
public function testUrlDoesContainQueryParamsIfMethodIsHead() |
241
|
|
|
{ |
242
|
|
|
$url = 'http://test.com'; |
243
|
|
|
|
244
|
|
|
$data = array( |
245
|
|
|
'test_param1' => 'Testing1', |
246
|
|
|
'test_param2' => 'Testing2' |
247
|
|
|
); |
248
|
|
|
|
249
|
|
|
$captureRequest = $this->getCaptureRequest(); |
250
|
|
|
$captureRequest->setMethod('HEAD'); |
251
|
|
|
$captureRequest->setUrl($url); |
252
|
|
|
$captureRequest->setRequestData($data); |
253
|
|
|
|
254
|
|
|
$expectedUrl = $url . '?test_param1=Testing1&test_param2=Testing2'; |
255
|
|
|
|
256
|
|
|
$this->assertSame($expectedUrl, $captureRequest->getUrl()); |
257
|
|
|
} |
258
|
|
|
|
259
|
|
|
/** |
260
|
|
|
* Test query params are appended to URL if |
261
|
|
|
* URL contains existng query params. |
262
|
|
|
* |
263
|
|
|
* @access public |
264
|
|
|
* @return void |
265
|
|
|
*/ |
266
|
|
|
public function testQueryParamsAreAppendedToUrlIfUrlContainsExistingQueryParams() |
267
|
|
|
{ |
268
|
|
|
$url = 'http://test.com?existing_param=Existing'; |
269
|
|
|
|
270
|
|
|
$data = array( |
271
|
|
|
'test_param1' => 'Testing1', |
272
|
|
|
'test_param2' => 'Testing2' |
273
|
|
|
); |
274
|
|
|
|
275
|
|
|
$captureRequest = $this->getCaptureRequest(); |
276
|
|
|
$captureRequest->setMethod('GET'); |
277
|
|
|
$captureRequest->setUrl($url); |
278
|
|
|
$captureRequest->setRequestData($data); |
279
|
|
|
|
280
|
|
|
$expectedUrl = $url . '&test_param1=Testing1&test_param2=Testing2'; |
281
|
|
|
|
282
|
|
|
$this->assertSame($expectedUrl, $captureRequest->getUrl()); |
283
|
|
|
} |
284
|
|
|
|
285
|
|
|
/** |
286
|
|
|
* Test request contains no body if method |
287
|
|
|
* is GET. |
288
|
|
|
* |
289
|
|
|
* @access public |
290
|
|
|
* @return void |
291
|
|
|
*/ |
292
|
|
|
public function testRequestContainsNoBodyIfMethodIsGet() |
293
|
|
|
{ |
294
|
|
|
$data = array( |
295
|
|
|
'test_param1' => 'Testing1', |
296
|
|
|
'test_param2' => 'Testing2' |
297
|
|
|
); |
298
|
|
|
|
299
|
|
|
$captureRequest = $this->getCaptureRequest(); |
300
|
|
|
$captureRequest->setMethod('GET'); |
301
|
|
|
$captureRequest->setRequestData($data); |
302
|
|
|
|
303
|
|
|
$this->assertSame('', $captureRequest->getBody()); |
304
|
|
|
} |
305
|
|
|
|
306
|
|
|
/** |
307
|
|
|
* Test request contains no body if method |
308
|
|
|
* is HEAD. |
309
|
|
|
* |
310
|
|
|
* @access public |
311
|
|
|
* @return void |
312
|
|
|
*/ |
313
|
|
|
public function testRequestContainsNoBodyIfMethodIsHead() |
314
|
|
|
{ |
315
|
|
|
$data = array( |
316
|
|
|
'test_param1' => 'Testing1', |
317
|
|
|
'test_param2' => 'Testing2' |
318
|
|
|
); |
319
|
|
|
|
320
|
|
|
$captureRequest = $this->getCaptureRequest(); |
321
|
|
|
$captureRequest->setMethod('HEAD'); |
322
|
|
|
$captureRequest->setRequestData($data); |
323
|
|
|
|
324
|
|
|
$this->assertSame('', $captureRequest->getBody()); |
325
|
|
|
} |
326
|
|
|
|
327
|
|
|
/** |
328
|
|
|
* Test request contains a body if method is |
329
|
|
|
* not HEAD or GET. |
330
|
|
|
* |
331
|
|
|
* @access public |
332
|
|
|
* @return void |
333
|
|
|
*/ |
334
|
|
|
public function testRequestContainsABodyIfMethodIsNotHeadOrGet() |
335
|
|
|
{ |
336
|
|
|
$data = array( |
337
|
|
|
'test_param1' => 'Testing1', |
338
|
|
|
'test_param2' => 'Testing2' |
339
|
|
|
); |
340
|
|
|
|
341
|
|
|
$captureRequest = $this->getCaptureRequest(); |
342
|
|
|
$captureRequest->setMethod('POST'); |
343
|
|
|
$captureRequest->setRequestData($data); |
344
|
|
|
|
345
|
|
|
$body = 'test_param1=Testing1&test_param2=Testing2'; |
346
|
|
|
|
347
|
|
|
$this->assertSame($body, $captureRequest->getBody()); |
348
|
|
|
} |
349
|
|
|
|
350
|
|
|
/** |
351
|
|
|
* Test request data can be flattened. |
352
|
|
|
* |
353
|
|
|
* @access public |
354
|
|
|
* @return void |
355
|
|
|
*/ |
356
|
|
|
public function testRequestDataCanBeFalttened() |
357
|
|
|
{ |
358
|
|
|
$data = array( |
359
|
|
|
'test_param1' => 'Testing1', |
360
|
|
|
'test_param2' => array( |
361
|
|
|
'Testing2', |
362
|
|
|
'Testing3' |
363
|
|
|
) |
364
|
|
|
); |
365
|
|
|
|
366
|
|
|
$captureRequest = $this->getCaptureRequest(); |
367
|
|
|
$captureRequest->setRequestData($data); |
368
|
|
|
|
369
|
|
|
$flatData = array( |
370
|
|
|
'test_param1' => 'Testing1', |
371
|
|
|
'test_param2[0]' => 'Testing2', |
372
|
|
|
'test_param2[1]' => 'Testing3' |
373
|
|
|
); |
374
|
|
|
|
375
|
|
|
$this->assertSame($flatData, $captureRequest->getRequestData(true)); |
376
|
|
|
} |
377
|
|
|
|
378
|
|
|
/** |
379
|
|
|
* Test raw request data can be accessed. |
380
|
|
|
* |
381
|
|
|
* @access public |
382
|
|
|
* @return void |
383
|
|
|
*/ |
384
|
|
|
public function testRawRequestDataCanBeAccessed() |
385
|
|
|
{ |
386
|
|
|
$data = array( |
387
|
|
|
'test_param1' => 'Testing1', |
388
|
|
|
'test_param2' => array( |
389
|
|
|
'Testing2', |
390
|
|
|
'Testing3' |
391
|
|
|
) |
392
|
|
|
); |
393
|
|
|
|
394
|
|
|
$captureRequest = $this->getCaptureRequest(); |
395
|
|
|
$captureRequest->setRequestData($data); |
396
|
|
|
|
397
|
|
|
$this->assertSame($data, $captureRequest->getRequestData(false)); |
398
|
|
|
} |
399
|
|
|
|
400
|
|
|
/** |
401
|
|
|
* Test headers can be added. |
402
|
|
|
* |
403
|
|
|
* @access public |
404
|
|
|
* @return void |
405
|
|
|
*/ |
406
|
|
|
public function testHeadersCanBeAdded() |
407
|
|
|
{ |
408
|
|
|
$existingHeaders = array( |
409
|
|
|
'Header1' => 'Header 1' |
410
|
|
|
); |
411
|
|
|
|
412
|
|
|
$newHeaders = array( |
413
|
|
|
'Header2' => 'Header 2', |
414
|
|
|
'Header3' => 'Header 3' |
415
|
|
|
); |
416
|
|
|
|
417
|
|
|
$captureRequest = $this->getCaptureRequest(); |
418
|
|
|
$captureRequest->setHeaders($existingHeaders); |
419
|
|
|
$captureRequest->addHeaders($newHeaders); |
420
|
|
|
|
421
|
|
|
$expectedHeaders = array_merge($existingHeaders, $newHeaders); |
422
|
|
|
|
423
|
|
|
$this->assertSame($expectedHeaders, $captureRequest->getHeaders()); |
424
|
|
|
} |
425
|
|
|
|
426
|
|
|
/** |
427
|
|
|
* Test headers can be accessed in |
428
|
|
|
* JSON format |
429
|
|
|
* |
430
|
|
|
* @access public |
431
|
|
|
* @return void |
432
|
|
|
*/ |
433
|
|
|
public function testHeadersCanBeAccessedInJsonFormat() |
434
|
|
|
{ |
435
|
|
|
$headers = array( |
436
|
|
|
'Header1' => 'Header 1', |
437
|
|
|
'Header2' => 'Header 2' |
438
|
|
|
); |
439
|
|
|
|
440
|
|
|
$captureRequest = $this->getCaptureRequest(); |
441
|
|
|
$captureRequest->setHeaders($headers); |
442
|
|
|
|
443
|
|
|
$expectedHeaders = json_encode($headers); |
444
|
|
|
|
445
|
|
|
$this->assertSame($expectedHeaders, $captureRequest->getHeaders('json')); |
446
|
|
|
} |
447
|
|
|
|
448
|
|
|
/** |
449
|
|
|
* Test raw headers can be accessed. |
450
|
|
|
* |
451
|
|
|
* @access public |
452
|
|
|
* @return void |
453
|
|
|
*/ |
454
|
|
|
public function testRawHeadersCanBeAccessed() |
455
|
|
|
{ |
456
|
|
|
$headers = array( |
457
|
|
|
'Header1' => 'Header 1', |
458
|
|
|
'Header2' => 'Header 2' |
459
|
|
|
); |
460
|
|
|
|
461
|
|
|
$captureRequest = $this->getCaptureRequest(); |
462
|
|
|
$captureRequest->setHeaders($headers); |
463
|
|
|
|
464
|
|
|
$this->assertSame($headers, $captureRequest->getHeaders('default')); |
465
|
|
|
} |
466
|
|
|
|
467
|
|
|
/** |
468
|
|
|
* Test not writable exception is thrown if |
469
|
|
|
* output path is not writable. |
470
|
|
|
* |
471
|
|
|
* @access public |
472
|
|
|
* @return void |
473
|
|
|
*/ |
474
|
|
|
public function testNotWritableExceptonIsThrownIfOutputPathIsNotWritable() |
475
|
|
|
{ |
476
|
|
|
$this->setExpectedException('\JonnyW\PhantomJs\Exception\NotWritableException'); |
|
|
|
|
477
|
|
|
|
478
|
|
|
$invalidPath = '/invalid/path'; |
479
|
|
|
|
480
|
|
|
$captureRequest = $this->getCaptureRequest(); |
481
|
|
|
$captureRequest->setOutputFile($invalidPath); |
482
|
|
|
} |
483
|
|
|
|
484
|
|
|
/** |
485
|
|
|
* Test can set output file. |
486
|
|
|
* |
487
|
|
|
* @access public |
488
|
|
|
* @return void |
489
|
|
|
*/ |
490
|
|
|
public function testCanSetOutputFile() |
491
|
|
|
{ |
492
|
|
|
$outputFile = sprintf('%s/test.jpg', sys_get_temp_dir()); |
493
|
|
|
|
494
|
|
|
$captureRequest = $this->getCaptureRequest(); |
495
|
|
|
$captureRequest->setOutputFile($outputFile); |
496
|
|
|
|
497
|
|
|
$this->assertSame($outputFile, $captureRequest->getOutputFile()); |
498
|
|
|
} |
499
|
|
|
|
500
|
|
|
/** |
501
|
|
|
* Test can set viewport width. |
502
|
|
|
* |
503
|
|
|
* @access public |
504
|
|
|
* @return void |
505
|
|
|
*/ |
506
|
|
|
public function testCanSetViewportWidth() |
507
|
|
|
{ |
508
|
|
|
$width = 100; |
509
|
|
|
$height = 200; |
510
|
|
|
|
511
|
|
|
$caputreRequest = $this->getCaptureRequest(); |
512
|
|
|
$caputreRequest->setViewportSize($width, $height); |
513
|
|
|
|
514
|
|
|
$this->assertSame($width, $caputreRequest->getViewportWidth()); |
515
|
|
|
} |
516
|
|
|
|
517
|
|
|
/** |
518
|
|
|
* Test can set viewport height. |
519
|
|
|
* |
520
|
|
|
* @access public |
521
|
|
|
* @return void |
522
|
|
|
*/ |
523
|
|
|
public function testCanSetViewportHeight() |
524
|
|
|
{ |
525
|
|
|
$width = 100; |
526
|
|
|
$height = 200; |
527
|
|
|
|
528
|
|
|
$caputreRequest = $this->getCaptureRequest(); |
529
|
|
|
$caputreRequest->setViewportSize($width, $height); |
530
|
|
|
|
531
|
|
|
$this->assertSame($height, $caputreRequest->getViewportHeight()); |
532
|
|
|
} |
533
|
|
|
|
534
|
|
|
/** +++++++++++++++++++++++++++++++++++ **/ |
535
|
|
|
/** ++++++++++ TEST ENTITIES ++++++++++ **/ |
536
|
|
|
/** +++++++++++++++++++++++++++++++++++ **/ |
537
|
|
|
|
538
|
|
|
/** |
539
|
|
|
* Get capture request instance. |
540
|
|
|
* |
541
|
|
|
* @access protected |
542
|
|
|
* @param string $url (default: null) |
543
|
|
|
* @param string $method (default: RequestInterface::METHOD_GET) |
544
|
|
|
* @param int $timeout (default: 5000) |
545
|
|
|
* @return \JonnyW\PhantomJs\Http\CaptureRequest |
546
|
|
|
*/ |
547
|
|
|
protected function getCaptureRequest($url = null, $method = RequestInterface::METHOD_GET, $timeout = 5000) |
548
|
|
|
{ |
549
|
|
|
$captureRequest = new CaptureRequest($url, $method, $timeout); |
550
|
|
|
|
551
|
|
|
return $captureRequest; |
552
|
|
|
} |
553
|
|
|
} |
554
|
|
|
|
This method has been deprecated. The supplier of the class has supplied an explanatory message.
The explanatory message should give you some clue as to whether and when the method will be removed from the class and what other method or class to use instead.