ZStar (JeroMQ 0.4.3 API)

java.lang.Object
- org.zeromq.ZStar

All Implemented Interfaces:

ZAgent

Direct Known Subclasses:

ZActor
```
public class ZStar
extends Object
implements ZAgent
```
First implementation for the base of a remotely controlled background service for 0MQ.
A side or endpoint designates the same thing: the thread where lives one of the two parts of the system.
A Star has 2 sides (with a trial to use theater terms for fun (: and hopefully clarity :)
- the Corbeille side, or control side
This is where one can send and receive control messages to the underneath star via the ZStar agent.
The ZStar lives on this side and is a way to safely communicate with the distant provided star.
Note: Corbeille is a french word designing the most privileged places in the theater where the King was standing, 1st floor, just above the orchestra (Wikipedia...).
- the Plateau side, or background side where all the performances are made by the provided star.
The provided star is living on the Plateau.
The Plateau is made of the Stage where effective acting takes place and of the Wings where the provided star can perform control decisions to stop or continue the acting.
From this side, the work is done via callbacks using the template-method pattern, applied with interfaces (?)
Communication between the 2 sides is ensured by pipes that SHALL NEVER be mixed between background and control sides.
Instead, each side use its own pipe to communicate with the other one, transmitting only 0MQ messages. The main purpose of this class is to ease this separation and to provide contracts, responsibilities and action levers for each side.
For example, instead of using pipe() which is useful to have more control, fast users would want to call agent() to get the agent or directly call send(ZMsg) or recv() from the ZStar as the ZStar is itself an agent!
The ZStar takes care of the establishment of the background processing, calling the provided star at appropriate times. It can also manage the exited state on the control side, if providing a non-null "Mot de la Fin".
It also takes care of the closing of sockets and context if it had to create one.
A star is basically a contract interface that anyone who uses this ZStar to create a background service SHALL comply to.

PS: Je sais qu'il y a une différence entre acteur et comédien :) PPS: I know nothing about theater!
For an example of code, please refer to the ZActor source code.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static interface`	`ZStar.Entourage` Utility class with calls surrounding the execution of the Star.
`static interface`	`ZStar.Exit` Control for the end of the remote operations.
`static interface`	`ZStar.Fortune`
`static interface`	`ZStar.Set`
`static class`	`ZStar.SimpleSet`
`static interface`	`ZStar.Star` Contract interface when acting in plain sight.
`static interface`	`ZStar.TimeTaker` Utility class with callback for when the Star has finished its performances.

Nested classes/interfaces inherited from interface org.zeromq.ZAgent
ZAgent.Creator, ZAgent.SelectorCreator, ZAgent.SimpleAgent, ZAgent.VerySimpleSelectorCreator

Constructor Summary

Constructors
Constructor and Description
`ZStar(ZAgent.SelectorCreator selector, ZStar.Fortune fortune, String motdelafin, Object... args)` Creates a new ZStar.
`ZStar(ZContext context, ZAgent.SelectorCreator selector, ZStar.Fortune fortune, String motdelafin, Object... bags)` Creates a new ZStar.
`ZStar(ZStar.Fortune actor, String lock, Object... args)` Creates a new ZStar.

Method Summary

Methods
Modifier and Type	Method and Description
`ZAgent`	`agent()` Returns the Corbeille endpoint.
`protected ZAgent`	`agent(ZMQ.Socket phone, String secret)` Creates a new agent for the star.
`void`	`close()` Closes the pipe.
`ZStar.Exit`	`exit()` Returns the control of the proper exit of the remote operations.
`static void`	`party(long time, TimeUnit unit)`
`ZMQ.Socket`	`pipe()` Returns the socket used for communication.
`ZMsg`	`recv()` Receives a control message sent from the Plateau in the Corbeille.
`ZMsg`	`recv(boolean wait)` Receives a control message sent from the Plateau in the Corbeille.
`ZMsg`	`recv(int timeout)` Receives a control message sent from the Plateau in the Corbeille.
`boolean`	`send(String word)` Sends a control message from the Corbeille to the Plateau side.
`boolean`	`send(String word, boolean more)` Sends a control message from the Corbeille to the Plateau side.
`boolean`	`send(ZMsg message)` Sends a control message from the Corbeille to the Plateau.
`boolean`	`send(ZMsg msg, boolean destroy)` Sends a control message from Corbeille side to the Plateau side.
`boolean`	`sign()` Gives a sign if the distant Star is here.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - ZStar
```
public ZStar(ZStar.Fortune actor,
     String lock,
     Object... args)
```
    Creates a new ZStar.
    
    Parameters:
    actor - the creator of stars on the Plateau
    lock - the final word used to mark the end of the star. Null to disable this mechanism.
    args - the optional arguments that will be passed to the distant star
  - ZStar
```
public ZStar(ZAgent.SelectorCreator selector,
     ZStar.Fortune fortune,
     String motdelafin,
     Object... args)
```
    Creates a new ZStar.
    
    Parameters:
    selector - the creator of the selector used on the Plateau.
    fortune - the creator of stars on the Plateau
    motdelafin - the final word used to mark the end of the star. Null to disable this mechanism.
    args - the optional arguments that will be passed to the distant star
  - ZStar
```
public ZStar(ZContext context,
     ZAgent.SelectorCreator selector,
     ZStar.Fortune fortune,
     String motdelafin,
     Object... bags)
```
    Creates a new ZStar.
    
    Parameters:
    context - the main context used. If null, a new context will be created and closed at the stop of the operation. If not null, it is the responsibility of the caller to close it.
    selector - the creator of the selector used on the Plateau.
    fortune - the creator of stars on the Plateau
    motdelafin - the final word used to mark the end of the star. Null to disable this mechanism.
    bags - the optional arguments that will be passed to the distant star
- Method Detail
  - party
```
public static void party(long time,
         TimeUnit unit)
```
  - agent
```
public ZAgent agent()
```
    Returns the Corbeille endpoint. Can be used to send or receive control messages to the distant star via Backstage.
    
    Returns:
    the agent/mailbox used to send and receive control messages to and from the star.
  - exit
```
public ZStar.Exit exit()
```
    Returns the control of the proper exit of the remote operations.
    
    Returns:
    a structure used for checking the end of the remote operations.
  - agent
```
protected ZAgent agent(ZMQ.Socket phone,
           String secret)
```
    Creates a new agent for the star. This method is called in the constructor so don't rely on private members to do the job. Apart from that, it is the last call so can be safely overridden from the ZStar point-of-view BUT if you don't make it final, one of your subclass could make you misery...
    
    Parameters:
    phone - the socket used to communicate with the star
    secret - the specific keyword indicating the death of the star and locking the agent. Null to override the lock mechanism.
    
    Returns:
    the newly created agent for the star.
  - recv
```
public ZMsg recv()
```
    Description copied from interface: ZAgent
    
    Receives a control message sent from the Plateau in the Corbeille. The call is blocking.
    
    Specified by:
    
    recv in interface ZAgent
    
    Returns:
    the received message or null if the context was shut down.
  - recv
```
public ZMsg recv(int timeout)
```
    Description copied from interface: ZAgent
    
    Receives a control message sent from the Plateau in the Corbeille. The call times out if there is no message after the elapsed time.
    
    Specified by:
    
    recv in interface ZAgent
    
    Parameters:
    timeout - the timeout in milliseconds before returning null.
    
    Returns:
    the received message or null if the context was shut down or if no message after the timeout.
  - recv
```
public ZMsg recv(boolean wait)
```
    Description copied from interface: ZAgent
    
    Receives a control message sent from the Plateau in the Corbeille. The call is blocking depending on the parameter.
    
    Specified by:
    
    recv in interface ZAgent
    
    Parameters:
    wait - true to make a blocking call, false to not wait, and possibly return null
    
    Returns:
    the received message or null if the context was shut down or if there is no message when not blocking.
  - send
```
public boolean send(ZMsg message)
```
    Description copied from interface: ZAgent
    
    Sends a control message from the Corbeille to the Plateau.
    
    Specified by:
    
    send in interface ZAgent
    
    Parameters:
    message - the message to send
    
    Returns:
    true if the message was sent, otherwise false (if the distant Star is dead for example)
  - send
```
public boolean send(ZMsg msg,
           boolean destroy)
```
    Description copied from interface: ZAgent
    
    Sends a control message from Corbeille side to the Plateau side.
    
    Specified by:
    
    send in interface ZAgent
    
    Parameters:
    msg - the message to send
    destroy - true to destroy the message after sending it.
    
    Returns:
    true if the message was sent, otherwise false (if the distant Star is dead for example)
  - send
```
public boolean send(String word)
```
    Description copied from interface: ZAgent
    
    Sends a control message from the Corbeille to the Plateau side.
    
    Specified by:
    
    send in interface ZAgent
    
    Parameters:
    word - the message to send
    
    Returns:
    true if the message was sent, otherwise false (if the distant Star is dead for example)
  - send
```
public boolean send(String word,
           boolean more)
```
    Description copied from interface: ZAgent
    
    Sends a control message from the Corbeille to the Plateau side.
    
    Specified by:
    
    send in interface ZAgent
    
    Parameters:
    word - the message to send
    more - true to send more strings in a single message
    
    Returns:
    true if the message was sent, otherwise false (if the distant Star is dead for example)
  - pipe
```
public ZMQ.Socket pipe()
```
    Description copied from interface: ZAgent
    
    Returns the socket used for communication. For advanced usage.
    
    Specified by:
    
    pipe in interface ZAgent
    
    Returns:
    the socket used to communicate with the distant Star.
  - sign
```
public boolean sign()
```
    Description copied from interface: ZAgent
    
    Gives a sign if the distant Star is here.
    
    Specified by:
    
    sign in interface ZAgent
    
    Returns:
    true if here, otherwise false
  - close
```
public void close()
```
    Description copied from interface: ZAgent
    
    Closes the pipe.
    
    Specified by:
    
    close in interface ZAgent

Class ZStar

Nested Class Summary

Nested classes/interfaces inherited from interface org.zeromq.ZAgent

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

ZStar

ZStar

ZStar

Method Detail

party

agent

exit

agent

recv

recv

recv

send

send

send

send

pipe

sign

close