io.spine.server.bus

Interface BusFilter<E extends MessageEnvelope<?,?,?>>

All Superinterfaces:

java.lang.AutoCloseable

All Known Implementing Classes:

CommandScheduler, ExecutorCommandScheduler

@SPI
 @FunctionalInterface
public interface BusFilter<E extends MessageEnvelope<?,?,?>>
extends java.lang.AutoCloseable

The filter for the messages posted to a bus.

A bus may have several filters which can prevent a message from being posted.

Method Summary

Modifier and Type	Method and Description
default void	close()
java.util.Optional<io.spine.core.Ack>	filter(E envelope) Accepts or rejects a passed message.
default java.util.Optional<io.spine.core.Ack>	letPass() Lets the message pass the filter.
default java.util.Optional<io.spine.core.Ack>	reject(E envelope) Rejects the message with the OK status.
default java.util.Optional<io.spine.core.Ack>	reject(E envelope, io.spine.base.Error cause) Rejects the message with an Error status.
default java.util.Optional<io.spine.core.Ack>	reject(E envelope, io.spine.base.ThrowableMessage cause) Rejects the message with a rejection status.

Method Detail

filter

java.util.Optional<io.spine.core.Ack> filter(E envelope)

Accepts or rejects a passed message.

A filter can:

• accept the message (by returning Optional.empty());
• reject the message with Error status, for example, if it fails to pass the validation;
• reject the message with OK status. For example, a scheduled command may not pass a filter;
• reject the message with a business rejection. For example, a command can be rejected if the user who made the request does not have enough permissions in the system. Such rejection is only applicable to commands.

Parameters:

envelope - the envelope with the message to filter

Returns:

Optional.empty() if the message passes the filter, posting result with either status otherwise

letPass

default java.util.Optional<io.spine.core.Ack> letPass()

Lets the message pass the filter.

This method is a shortcut which can be used in BusFilter.filter(MessageEnvelope) when this filter shouldn't prevent the message from being posted.

reject

default java.util.Optional<io.spine.core.Ack> reject(E envelope)

Rejects the message with the OK status.

This method is a shortcut which can be used in BusFilter.filter(MessageEnvelope) when the message does not pass the filter and this is expected.

Parameters:

envelope - the envelope with the message to filter

Returns:

the Optional.of(Ack) signaling that the message does not pass the filter

reject

default java.util.Optional<io.spine.core.Ack> reject(E envelope,
                                                     io.spine.base.Error cause)

Rejects the message with an Error status.

This method is a shortcut which can be used in BusFilter.filter(MessageEnvelope) when the message does not pass the filter due to a technical error or inconsistency in model data.

Parameters:

envelope - the envelope with the message to filter

cause - the cause of the rejection

Returns:

the Optional.of(Ack) signaling that the message does not pass the filter

reject

default java.util.Optional<io.spine.core.Ack> reject(E envelope,
                                                     io.spine.base.ThrowableMessage cause)

Rejects the message with a rejection status.

This method is a shortcut which can be used in BusFilter.filter(MessageEnvelope) when the message does not pass the filter due to a business rejection.

Such rejection method can be used when no technical error occurs but due to the business rules the command should be immediately disqualified from being executed. A typical scenario would be when the permissions of the user who made the request aren't broad enough.

Parameters:

envelope - the envelope with the message to filter

cause - the cause of the rejection

Returns:

the Optional.of(Ack) signaling that the message does not pass the filter

Throws:

java.lang.IllegalArgumentException - if the filtered envelope is not a command

close

default void close()
            throws java.lang.Exception

By default, performs no action.

Specified by:

close in interface java.lang.AutoCloseable

Throws:

java.lang.Exception