| Creates a copy of a
Message .
This method creates a new
Message whose header/payload/attachments/properties
are identical to this
Message . Once created, the created
Message and the original
Message behaves independently --- adding header/
attachment to one
Message doesn't affect another
Message at all.
This method does NOT consume a message.
To enable efficient copy operations, there's a few restrictions on
how copied message can be used.
- The original and the copy may not be
used concurrently by two threads (this allows two
Message s
to share some internal resources, such as JAXB marshallers.)
Note that it's OK for the original and the copy to be processed
by two threads, as long as they are not concurrent.
- The copy has the same 'life scope'
as the original (this allows shallower copy, such as
JAXB beans wrapped in
JAXBMessage .)
A 'life scope' of a message created during a message processing
in a pipeline is until a pipeline processes the next message.
A message cannot be kept beyond its life scope.
(This experimental design is to allow message objects to be reused
--- feedback appreciated.)
Design Rationale
Since a
Message body is read-once, sometimes
(such as when you do fail-over, or WS-RM) you need to
create an idential copy of a
Message .
The actual copy operation depends on the layout
of the data in memory, hence it's best to be done by
the
Message implementation itself.
The restrictions placed on the use of copied
Message can be
relaxed if necessary, but it will make the copy method more expensive.
|