Mail::Box::Message::Destructed(3pm)

1Mail::Box::Message::DesUtsreurctCeodn(t3r)ibuted Perl DoMcauimle:n:tBaotxi:o:nMessage::Destructed(3)
2
3
4

NAME

6       Mail::Box::Message::Destructed - a destructed message
7

INHERITANCE

9        Mail::Box::Message::Destructed
10          is a Mail::Box::Message
11          is a Mail::Message
12          is a Mail::Reporter
13

SYNOPSIS

15        $folder->message(3)->destruct;
16

DESCRIPTION

18       When a message folder is read, each message will be parsed into Perl
19       structures.  Especially the header structure can consume a huge amount
20       of memory (message bodies can be moved to external temporary files).
21       Destructed messages have forcefully cleaned-up all header and body
22       information, and are therefore much smaller.  Some useful information
23       is still in the object.
24
25       BE WARNED: once a message is destructed, it cannot be revived.
26       Destructing enforces irreversable deletion from the folder.  If you
27       have a folder opened for read-only, the message will stay in that
28       folder, but otherwise it may be deleted.
29

METHODS

31   Constructors
32       $obj->clone(OPTIONS)
33           See "Constructors" in Mail::Message
34
35       Mail::Box::Message::Destructed->new(MESSAGE-ID, OPTIONS)
36           You cannot instantiate a destructed message object.  Destruction is
37           done by calling Mail::Box::Message::destruct().
38
39            -Option    --Defined in     --Default
40             body        Mail::Message    undef
41             body_type   Mail::Box::Message  <from folder>
42             deleted     Mail::Message    <false>
43             field_type  Mail::Message    undef
44             folder      Mail::Box::Message  <required>
45             head        Mail::Message    undef
46             head_type   Mail::Message    Mail::Message::Head::Complete
47             labels      Mail::Message    {}
48             log         Mail::Reporter   'WARNINGS'
49             messageId   Mail::Message    undef
50             modified    Mail::Message    <false>
51             size        Mail::Box::Message  undef
52             trace       Mail::Reporter   'WARNINGS'
53             trusted     Mail::Message    <false>
54
55           body => OBJECT
56           body_type => CODE|CLASS
57           deleted => BOOLEAN
58           field_type => CLASS
59           folder => FOLDER
60           head => OBJECT
61           head_type => CLASS
62           labels => ARRAY|HASH
63           log => LEVEL
64           messageId => STRING
65           modified => BOOLEAN
66           size => INTEGER
67           trace => LEVEL
68           trusted => BOOLEAN
69
70   Constructing a message
71       $obj->bounce([RG-OBJECT|OPTIONS])
72           See "Constructing a message" in Mail::Message::Construct::Bounce
73
74       Mail::Box::Message::Destructed->build([MESSAGE|PART|BODY], CONTENT)
75           See "Constructing a message" in Mail::Message::Construct::Build
76
77       Mail::Box::Message::Destructed->buildFromBody(BODY, [HEAD], HEADERS)
78           See "Constructing a message" in Mail::Message::Construct::Build
79
80       $obj->forward(OPTIONS)
81           See "Constructing a message" in Mail::Message::Construct::Forward
82
83       $obj->forwardAttach(OPTIONS)
84           See "Constructing a message" in Mail::Message::Construct::Forward
85
86       $obj->forwardEncapsulate(OPTIONS)
87           See "Constructing a message" in Mail::Message::Construct::Forward
88
89       $obj->forwardInline(OPTIONS)
90           See "Constructing a message" in Mail::Message::Construct::Forward
91
92       $obj->forwardNo(OPTIONS)
93           See "Constructing a message" in Mail::Message::Construct::Forward
94
95       $obj->forwardPostlude
96           See "Constructing a message" in Mail::Message::Construct::Forward
97
98       $obj->forwardPrelude
99           See "Constructing a message" in Mail::Message::Construct::Forward
100
101       $obj->forwardSubject(STRING)
102           See "Constructing a message" in Mail::Message::Construct::Forward
103
104       Mail::Box::Message::Destructed->read(FILEHANDLE|SCALAR|REF-SCALAR|ARRAY-OF-LINES,
105       OPTIONS)
106           See "Constructing a message" in Mail::Message::Construct::Read
107
108       $obj->rebuild(OPTIONS)
109           See "Constructing a message" in Mail::Message::Construct::Rebuild
110
111       $obj->reply(OPTIONS)
112           See "Constructing a message" in Mail::Message::Construct::Reply
113
114       $obj->replyPrelude([STRING|FIELD|ADDRESS|ARRAY-OF-THINGS])
115           See "Constructing a message" in Mail::Message::Construct::Reply
116
117       $obj->replySubject(STRING)
118           Mail::Box::Message::Destructed->replySubject(STRING)
119
120           See "Constructing a message" in Mail::Message::Construct::Reply
121
122   The message
123       $obj->container
124           See "The message" in Mail::Message
125
126       $obj->copyTo(FOLDER, OPTIONS)
127           See "The message" in Mail::Box::Message
128
129       $obj->folder([FOLDER])
130           See "The message" in Mail::Box::Message
131
132       $obj->isDummy
133           See "The message" in Mail::Message
134
135       $obj->isPart
136           See "The message" in Mail::Message
137
138       $obj->messageId
139           See "The message" in Mail::Message
140
141       $obj->moveTo(FOLDER, OPTIONS)
142           See "The message" in Mail::Box::Message
143
144       $obj->print([FILEHANDLE])
145           See "The message" in Mail::Message
146
147       $obj->send([MAILER], OPTIONS)
148           See "The message" in Mail::Message
149
150       $obj->seqnr([INTEGER])
151           See "The message" in Mail::Box::Message
152
153       $obj->size
154           See "The message" in Mail::Message
155
156       $obj->toplevel
157           See "The message" in Mail::Message
158
159       $obj->write([FILEHANDLE])
160           See "The message" in Mail::Message
161
162   The header
163       $obj->bcc
164           See "The header" in Mail::Message
165
166       $obj->cc
167           See "The header" in Mail::Message
168
169       $obj->date
170           See "The header" in Mail::Message
171
172       $obj->destinations
173           See "The header" in Mail::Message
174
175       $obj->from
176           See "The header" in Mail::Message
177
178       $obj->get(FIELDNAME)
179           See "The header" in Mail::Message
180
181       $obj->guessTimestamp
182           See "The header" in Mail::Message
183
184       $obj->head([HEAD])
185           When "undef" is specified for HEAD, no change has to take place and
186           the method returns silently.  In all other cases, this method will
187           complain that the header has been removed.
188
189       $obj->nrLines
190           See "The header" in Mail::Message
191
192       $obj->sender
193           See "The header" in Mail::Message
194
195       $obj->study(FIELDNAME)
196           See "The header" in Mail::Message
197
198       $obj->subject
199           See "The header" in Mail::Message
200
201       $obj->timestamp
202           See "The header" in Mail::Message
203
204       $obj->to
205           See "The header" in Mail::Message
206
207   The body
208       $obj->body([BODY])
209           When "undef" is specified for BODY, no change has to take place and
210           the method returns silently.  In all other cases, this method will
211           complain that the body data has been removed.
212
213       $obj->contentType
214           See "The body" in Mail::Message
215
216       $obj->decoded(OPTIONS)
217           See "The body" in Mail::Message
218
219       $obj->encode(OPTIONS)
220           See "The body" in Mail::Message
221
222       $obj->isMultipart
223           See "The body" in Mail::Message
224
225       $obj->isNested
226           See "The body" in Mail::Message
227
228       $obj->parts(['ALL'|'ACTIVE'|'DELETED'|'RECURSE'|FILTER])
229           See "The body" in Mail::Message
230
231   Flags
232       $obj->delete
233           See "Flags" in Mail::Message
234
235       $obj->deleted([BOOLEAN])
236           See "Flags" in Mail::Message
237
238       $obj->isDeleted
239           See "Flags" in Mail::Message
240
241       $obj->isModified
242           See "Flags" in Mail::Message
243
244       $obj->label(LABEL|PAIRS)
245           It is possible to delete a destructed message, but not to undelete
246           it.
247
248       $obj->labels
249           See "Flags" in Mail::Message
250
251       $obj->labelsToStatus
252           See "Flags" in Mail::Message
253
254       $obj->modified([BOOLEAN])
255           See "Flags" in Mail::Message
256
257       $obj->statusToLabels
258           See "Flags" in Mail::Message
259
260   The whole message as text
261       $obj->file
262           See "The whole message as text" in Mail::Message::Construct::Text
263
264       $obj->lines
265           See "The whole message as text" in Mail::Message::Construct::Text
266
267       $obj->printStructure([FILEHANDLE|undef],[INDENT])
268           See "The whole message as text" in Mail::Message::Construct::Text
269
270       $obj->string
271           See "The whole message as text" in Mail::Message::Construct::Text
272
273   Internals
274       $obj->clonedFrom
275           See "Internals" in Mail::Message
276
277       Mail::Box::Message::Destructed->coerce(MESSAGE)
278           Coerce a Mail::Box::Message into destruction.
279
280           example: of coercion to death
281
282            Mail::Box::Message::Destructed->coerce($folder->message(1));
283            $folder->message(1)->destruct;  # same
284
285            my $msg = $folder->message(1);
286            Mail::Box::Message::Destructed->coerce($msg);
287            $msg->destruct;                 # same
288
289       $obj->diskDelete
290           See "Internals" in Mail::Box::Message
291
292       $obj->isDelayed
293           See "Internals" in Mail::Message
294
295       $obj->readBody(PARSER, HEAD [, BODYTYPE])
296           See "Internals" in Mail::Box::Message
297
298       $obj->readFromParser(PARSER, [BODYTYPE])
299           See "Internals" in Mail::Message
300
301       $obj->readHead(PARSER [,CLASS])
302           See "Internals" in Mail::Message
303
304       $obj->recursiveRebuildPart(PART, OPTIONS)
305           See "Internals" in Mail::Message::Construct::Rebuild
306
307       $obj->storeBody(BODY)
308           See "Internals" in Mail::Message
309
310       $obj->takeMessageId([STRING])
311           See "Internals" in Mail::Message
312
313   Error handling
314       $obj->AUTOLOAD
315           See "METHODS" in Mail::Message::Construct
316
317       $obj->addReport(OBJECT)
318           See "Error handling" in Mail::Reporter
319
320       $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
321           Mail::Box::Message::Destructed->defaultTrace([LEVEL]|[LOGLEVEL,
322           TRACELEVEL]|[LEVEL, CALLBACK])
323
324           See "Error handling" in Mail::Reporter
325
326       $obj->errors
327           See "Error handling" in Mail::Reporter
328
329       $obj->log([LEVEL [,STRINGS]])
330           Mail::Box::Message::Destructed->log([LEVEL [,STRINGS]])
331
332           See "Error handling" in Mail::Reporter
333
334       $obj->logPriority(LEVEL)
335           Mail::Box::Message::Destructed->logPriority(LEVEL)
336
337           See "Error handling" in Mail::Reporter
338
339       $obj->logSettings
340           See "Error handling" in Mail::Reporter
341
342       $obj->notImplemented
343           See "Error handling" in Mail::Reporter
344
345       $obj->report([LEVEL])
346           See "Error handling" in Mail::Reporter
347
348       $obj->reportAll([LEVEL])
349           See "Error handling" in Mail::Reporter
350
351       $obj->shortSize([VALUE])
352           Mail::Box::Message::Destructed->shortSize([VALUE])
353
354           See "Error handling" in Mail::Message
355
356       $obj->shortString
357           See "Error handling" in Mail::Message
358
359       $obj->trace([LEVEL])
360           See "Error handling" in Mail::Reporter
361
362       $obj->warnings
363           See "Error handling" in Mail::Reporter
364
365   Cleanup
366       $obj->DESTROY
367           See "Cleanup" in Mail::Message
368
369       $obj->destruct
370           See "Cleanup" in Mail::Box::Message
371
372       $obj->inGlobalDestruction
373           See "Cleanup" in Mail::Reporter
374

DIAGNOSTICS

376       Error: Cannot coerce a (class) into destruction
377           Only real Mail::Box::Message objects can get destructed into
378           Mail::Box::Message::Destructed objects.  Mail::Message free their
379           memory immediately when the last reference is lost.
380
381       Error: Cannot include forward source as $include.
382           Unknown alternative for the forward(include).  Valid choices are
383           "NO", "INLINE", "ATTACH", and "ENCAPSULATE".
384
385       Error: Cannot include reply source as $include.
386           Unknown alternative for the "include" option of reply().  Valid
387           choices are "NO", "INLINE", and "ATTACH".
388
389       Error: Destructed message has no labels except 'deleted'
390       Error: Destructed messages can not be undeleted
391           Once a message is destructed, it can not be revived.  Destruction
392           is an optimization in memory usage: if you need an undelete
393           functionality, then you can not use Mail::Box::Message::destruct().
394
395       Error: Method bounce requires To, Cc, or Bcc
396           The message bounce() method forwards a received message off to
397           someone else without modification; you must specified it's new
398           destination.  If you have the urge not to specify any destination,
399           you probably are looking for reply(). When you wish to modify the
400           content, use forward().
401
402       Error: Method forwardAttach requires a preamble
403       Error: Method forwardEncapsulate requires a preamble
404       Error: No address to create forwarded to.
405           If a forward message is created, a destination address must be
406           specified.
407
408       Error: No default mailer found to send message.
409           The message send() mechanism had not enough information to
410           automatically find a mail transfer agent to sent this message.
411           Specify a mailer explicitly using the "via" options.
412
413       Error: No rebuild rule $name defined.
414       Error: Only build() Mail::Message's; they are not in a folder yet
415           You may wish to construct a message to be stored in a some kind of
416           folder, but you need to do that in two steps.  First, create a
417           normal Mail::Message, and then add it to the folder.  During this
418           Mail::Box::addMessage() process, the message will get coerce()-d
419           into the right message type, adding storage information and the
420           like.
421
422       Error: Package $package does not implement $method.
423           Fatal error: the specific package (or one of its superclasses) does
424           not implement this method where it should. This message means that
425           some other related classes do implement this method however the
426           class at hand does not.  Probably you should investigate this and
427           probably inform the author of the package.
428
429       Error: You cannot instantiate a destructed message
430           You cannot instantiate a destructed message object directly.
431           Destruction is done by calling Mail::Box::Message::destruct() on
432           any existing folder message.
433
434       Error: You cannot take the head/body of a destructed message
435           The message originated from a folder, but its memory has been
436           freed-up forcefully by means of Mail::Box::Message::destruct().
437           Apparently, your program still tries to get to the header or body
438           data after this destruction, which is not possible.
439

LICENSE

445       Copyrights 2001-2011 by Mark Overmeer. For other contributors see
446       ChangeLog.
447
448       This program is free software; you can redistribute it and/or modify it
449       under the same terms as Perl itself.  See
450       http://www.perl.com/perl/misc/Artistic.html
451
452
453
454perl v5.12.3                      2011-01-26 Mail::Box::Message::Destructed(3)