CEnvelope

A CEnvelope is part of every message. It carries the control data needed to deliver that message to a target in nyssr.net: sender, receiver, result, reply behavior, routing, priority, transport, and debugging information.

Choose an envelope for the destination

The factory methods at the beginning of this reference cover the most common destinations:

• a microservice resolved by ID
• a local or remote nano service
• a target addressed directly

Key idea: The envelope describes how a message travels; the record carries what the message means.

There are a few methods for creating envelopes.

Send to a microservice

The following method can be used to send a message to a microservice. The system looks for a microservice with just this ID and then enters the fully qualified target address.

@NotNull
public static CEnvelope forMicroService(@NotNull final IId aMicroServiceId);

Send to a nano service in the same node

To send a message to a nano service in the same node, the following method can be used. The namespace in which this nano service was registered is required:

@NotNull
public static CEnvelope forLocalNanoService(@NotNull final IId aNID);

The generated record class can also be used. But the record must be a nano service and must contain the namespace where the nano service was registered.

@NotNull
public static CEnvelope forLocalNanoService(@NotNull final Class aClass) throws CException;

Send to a nano service on another node

These methods are used to create an envelope for a message to another node.

@NotNull
public static CEnvelope forRemoteNanoService(@NotNull final IId aNID,
                                             @NotNull final CNodeId aNodeId);
@NotNull
public static CEnvelope forRemoteNanoService(@NotNull final IId aNID,
                                             @NotNull final CNodeAddress aNodeAddress);
@NotNull
public static CEnvelope forRemoteNanoService(@NotNull final Class aClass,
                                             @NotNull final CNodeAddress aNodeAddress) throws CException;

Send directly to a target

If the address of a target is known, you can also use these methods:

@NotNull
public static CEnvelope forSingleTarget(@Nullable final IId aTID,
                                        @Nullable final IId aNID,
                                        @Nullable final CNodeId aNodeId);
@NotNull
public static CEnvelope forSingleTarget(@Nullable final IId aTID,
                                        @Nullable final IId aNID,
                                        @Nullable final CNodeAddress aNodeAddress);
@NotNull
public static CEnvelope forSingleTarget(final CTargetAddress aReceiver);

Copy

There is also a static copy method:

@NotNull
public static CEnvelope copy(@NotNull final CEnvelope aEnvelope);

Stream

Messages can also be read from a DataInput stream and written to a DataOutput stream:

@NotNull
public static CEnvelope fromStream(@NotNull final DataInput aStream) throws IOException;
public void toStream(@NotNull final DataOutput aStream) throws IOException;

Default constructor

public CEnvelope(){}

Sender and receiver

An envelope contains one sender and normally one recipient address. The sender is usually set by CTarget. A receiver can be set directly or stored in the forwarding stack.

public void setSender(final CTargetAddress aSender);
@NotNull
public CTargetAddress getSender();
public void setReceiver(@Nullable final CTargetAddress aReceiver);
@NotNull
public CTargetAddress getReceiver();
@NotNull
public Stack<CTargetAddress> getReceivers();

A new receiver can be pushed for forwarding; a pop removes the current address. The message is not broadcast to every address in the stack.

Result and reply handshake

A response carries a result code and, optionally, result text. CResult contains both values. The sender can request an automatic answer with wantAnswer; delivery errors are returned even without that request.

public void setResult(final int aCode, final String aText);
public void setResultSuccess();
public int getResultCode();
public String getResultText();
public CResult getResult();
public void setIsAnswer(final boolean aIsAnswer);
public boolean isAnswer();
public void setWantAnswer(final boolean aWantAnswer);
public boolean wantAnswer();
public void setHandled(final boolean aHandled);
public boolean hasBeenHandled();

The response handshake is an essential nyssr.net feature. The sender retains control of the process until a positive response arrives and can then continue, retry, or choose another destination.

Blocked and forwarded messages

A handler can postpone a response while it performs follow-up work. It marks the envelope as blocked and sends it back manually when processing is complete.

public void setBlocked(final boolean aBlocked);
public boolean isBlocked();
public void forwardMessage(final CTargetAddress aReceiver);
public boolean shallForward();

Routing and transport options

The envelope can carry additional control data:

• microservice ID and nano-service flag
• transaction ID for correlating later responses
• onlyLocal to prevent a message leaving its node
• priority for hop-by-hop queue handling
• packet builder sequence for raw, compressed, or encrypted transport

public void setMicroServiceId(@Nullable final IId aMicroServiceId);
public IId getMicroServiceId();
public void setTransactionId(@Nullable final UUID aId);
public UUID getTransactionId();
public void setOnlyLocal(final boolean aOnlyLocal);
public boolean isOnlyLocal();
public void setPriority(@NotNull final EPriority aPriority);
public EPriority getPriority();
public void setPacketBuilderSequence(final String aSequence);
public String getPacketBuilderSequence();

Debugging and timestamps

Several timestamps and sequence values help diagnose delivery problems. Debug transport can be enabled when timestamps need to cross node boundaries.

public Instant getTimeSend();
public Instant getTimeDeliver();
public Instant getTimeSendBack();
public Instant getTimeDeliverAnswer();
public void setTimeSend(@Nullable final Instant aTimeSend);
public void setTimeDeliver(@Nullable final Instant aTimeDeliver);
public void setTimeSendBack(@Nullable final Instant aTimeSendBack);
public void setTimeDeliverAnswer(@Nullable final Instant aTimeDeliverAnswer);
public static void setDebug(final boolean aDebug);
public static boolean isDebug();
public void setLogEnabled(final boolean aEnabled);