Use this command to change properties of a bus destination for
a service integration bus.
This command provides only a subset of the properties available.
If you want to set other properties, you need to use the administrative console
or wsadmin and JACL
To run the command,
use the AdminTask object of the wsadmin scripting client.
The wsadmin
scripting client is run from Qshell. For more information, see the topic "Configure
Qshell to run WebSphere Application Server scripts".
This
command is only valid when used with WebSphere Application Server Version
6 and later application servers. Do not use it with earlier versions.
Command-line help
is provided for service integration bus commands:
For additional details of the command properties, see the
related reference topic.
Purpose
This command changes properties of a bus destination for a service integration bus.
- Command name
- modifySIBDestination
- Target
- Bus destination
- Result
- A bus destination object
(modified).
Required parameters
- -bus busname
- The name of the service integration bus on which the bus destination is
configured. You can use the listSIBuses command to list the names of existing
buses.
- -name destname
- The identifier by which this destination is known for administrative purposes.
Conditional parameters
None.
Optional parameters
- -description text
- An optional description for the bus destination,
for administrative purposes.
- -reliability BEST_EFFORT_NONPERSISTENT | EXPRESS_NONPERSISTENT | RELIABLE_NONPERSISTENT
| RELIABLE_PERSISTENT | ASSURED_PERSISTENT
- The reliability assigned to a message produced to this destination when an explicit reliability has not been set by the producer.
- BEST_EFFORT_NONPERSISTENT
- Messages are discarded when a messaging engine stops or fails. Messages may also be discarded if a connection used to send them becomes unavailable and as a result of constrained system resources.
For non-transactional JMS message-driven beans
and MessageListeners that use a JMS destination configured on the
default messaging provider, best-effort nonpersistent messages are
not recoverable. In this case, if a message is unlocked because the
message-driven bean or MessageListener threw an exception, then the
message is not redelivered or sent to the exception destination because
it was deleted from the message store when it was passed to the listener.
If you require higher message reliability for non-transactional JMS
message-driven beans and MessageListeners, configure a different option
for the Maximum reliability property of the bus destination.
- EXPRESS_NONPERSISTENT
- Messages are discarded when a messaging engine stops or fails. Messages may also be discarded if a connection used to send them becomes unavailable.
- RELIABLE_NONPERSISTENT
- Messages are discarded when a messaging engine stops or fails.
- RELIABLE_PERSISTENT
- Messages may be discarded when a messaging engine fails.
- ASSURED_PERSISTENT
- Messages are not discarded.
- -overrideOfQOSByProducerAllowed TRUE | FALSE
- Select this option to enable producers to override the default reliability that is set on the destination.
- -defaultPriority number
- The default priority assigned to messages sent to this destination when a priority has not been set by the producer. Specify
a value in the range 0 (lowest) through 9 (high).
- -maxFailedDeliveries number
- The maximum number of failed attempts to process a message before the message is forwarded to the exception destination for the destination. Specify
a value in the range 0 through 2147483647. A value of 0 (zero) means that
if a message cannot be delivered on the first attempt, it is either forwarded
to the exception destination or discarded, as defined by the exceptionDestination
property.
- -exceptionDestination destinationName
- The destination to which a message is forwarded by the system when it cannot be delivered to this destination.
- System
- The bus destination uses the default exception destination..
All messages that cannot be delivered to this destination are rerouted automatically
to the system default exception destination for the messaging engine that
this destination is assigned to; _SYSTEM.Exception.Destination.engine_name.
- None
- The bus destination has no exception destination..
The maximum failed deliveries count has no effect and undeliverable messages
are not rerouted to an exception destination. An undeliverable message can
block the processing of other messages waiting for delivery to the same destination.
This can be used to preserve message ordering, but this can have a detrimental
effect on the service integration bus.
- Specify
- The bus destination uses the exception destination specified in this field..
- -sendAllowed TRUE | FALSE
- Send allowed
- Selected
- Producers can send messages to this destination.
- Cleared
- Producers cannot send messages to this destination.
- For a queue point of a non-mediated destination, or a mediation point
of a mediated destination, new messages (from attached producers or forwarded
from another destination) are redirected to any available message point.
If no message points are available,
then messages that have already been accepted onto the bus, and new messages
from attached producers, are preserved by the bus until a message point becomes
available. The only exception to this is the case of a destination with only
one message point (queue point or mediation point depending on whether
the destination is mediated or non-mediated), where the producer is attached
to the same messaging engine. In
this case, an exception is thrown on each send call. The exception message
indicates that the reason for the exception is that the only extant localization
has been disabled for send. The producer remains open as normal, and any more
send calls succeed if the Send allowed property of
the localization is reselected (reset to true).
- For a queue point of a
mediated destination, clearing this Send allowed property
alters the behavior of the mediation instances that are sending to the destination
in the same way as setting it to false on a non-mediated destination affects
producing applications: Messages are sent instead to any alternative message point.
If no localizations are available, are preserved by the bus until a message point becomes
available. For any mediation instance (that is, on any server that has a mediation
point), if the same server hosts a queue point, and that queue point is the
only queue point for the destination, then the mediation changes to the "stopped
on error" state.
- -receiveAllowed TRUE | FALSE
- Clear this option (setting it to false) to prevent consumers from being able to receive messages from this destination.
- TRUE
- Consumers can get messages from this destination.
- FALSE
- Consumers cannot get messages from this destination.
For the message point,
any open consumers change state and an exception is thrown if the consumer
requests a message. Messages can continue to be sent, and accumulate on the message point.
- -maintainStrictMessageOrder TRUE | FALSE
- Maintain strict message order
- Selected
- Maintains the order in which a producer sends messages
to the destination.
At runtime, this property has
priority over other configuration property values. For information on the
configuration properties that are overridden at runtime, see Strict message ordering for bus destinations.
- Cleared
- Message order is not preserved for this destination.
- -quiesceMode TRUE | FALSE
- Quiesce mode
- -receiveExclusive TRUE | FALSE
- Receive exclusive
- -topicAccessCheckRequired
- [Topic space] Whether or not authorization checks are required for access to topics.
- -replyDestination
- The name of a destination to be appended to any non-empty reverse routing path of messages sent to this destination. This
property is intended for use with mediations on reply messages. For more information
about the use of this property, see Configuring a destination reverse routing path.
- -replyDestinationBus
- The bus on which the reply destination exists. This
property is intended for use with mediations on reply messages. For more information
about the use of this property, see Configuring a destination reverse routing path.
- -delegateAuthorizationCheckToTarget
- [Alias destination] Indicates whether the authorization check is performed on the alias or the target destination.
- -defaultForwardRoutingPath
- The value to which a message's forward routing path is set if the message contains no forward routing path, in the following format: {{bus1 destination1} {bus2 destination2}}
Example
wsadmin>$AdminTask showSIBDestination {-bus abus -name myqueue} {receiveExclusive=false,
defaultForwardRoutingPath=[], defaultPriority=0, exceptionDestination=$DEFAULT_EXCEPTION_DESTINATION,
uuid=97CC75AC71E5932CAB3417AC, overrideOfQOSByProducerAllowed=true, sendAllowed=true,
maxFailedDeliveries=5, maxReliability=ASSURED_PERSISTENT, reliability=ASSURED_PERSISTENT,
receiveAllowed=true, identifier=myqueue}
wsadmin>$AdminTask modifySIBDestination {-bus abus -name myqueue -receiveAllowed FALSE}
(cells/9994GKCCell01/buses/abus|sib-destinations.xml#SIBQueue_1098215169998)
wsadmin>$AdminTask showSIBDestination {-bus abus -name myqueue} {receiveExclusive=false,
defaultForwardRoutingPath=[], defaultPriority=0, exceptionDestination=$DEFAULT_EXCEPTION_DESTINATION,
uuid=97CC75AC71E5932CAB3417AC, overrideOfQOSByProducerAllowed=true, sendAllowed=true,
maxFailedDeliveries=5, maxReliability=ASSURED_PERSISTENT, reliability=ASSURED_PERSISTENT,
receiveAllowed=false, identifier=myqueue}