User reference manual

• Vocabulary
• Repository
• Primitives
  • General
  • Initiatives
  • Answers
  • Content management
• Customising
  • Tracing
  • Housekeeping
  • Anonymity
  • Automatism
• Interface

Vocabulary

The CO₄ protocol makes use of various notions that must be understood in order to manipulate them. These definitions can also be found in the glossary.

• Repository: a container of the description of the artefact to be built. In the following, the repository is a running process.
• Group repository: a repository that is fully automated and that is meant to contain the consensual representation among its subscribers.
• Agent name server (ANS): a process which has in charge the identification (and management of addresses) of the various repositories. It is identified by an URL. In Co4, the ANS also manages the data of the various repositories.
• Mailbox: the set of messages received by a repository. It is stored by the ANS when the repository is shut down.
• Initiative: a query issued by the current repository to its group repository.
• Proposal: under the interface, a proposal is a query that has been sent by the group repository (as a CFC), to be accepted, rejected or challenged by its subscribers.
• Call for comments (CFC): when the group repository receives an initiative, it sends it as a proposal to all the subscribers for a vote, and gathers all the answers. A CFC is an abstract representation of this voting procedure, and will be accepted, rejected or challenged.
• Log: the set of proposals that have been accepted in the group repository but have not been introduced into the current repository for various reasons.
• Surrogate: number identifying in a unique manner the message exchanged between repositories (the numbers are not unique, but the context -- i.e. the kind of message and who issued it -- warrants the identification of the message).

Repository

A CO₄ repository is defined by its name. It must be declared to an agent name server (ANS). A repository is thus created by declaring:

• the ANS URL (e.g. http://co4.inrialpes.fr:1080);
• the name of the repository (e.g. myrep);
• the URL of the repository (e.g. tcp://lotse.inrialpes.fr:5551).

Primitives

Once the repository has been created, there are various kinds of actions which can be performed. They are presented below.

General

General primitives () deal with the system issues of starting and stopping a repository. These actions are not part of the CO₄ protocol but they are necessary to its everyday work.

• CREATE: the repository is created and known to the ANS.
• DELETE: the repository is discarded from the ANS together with its mailbox and content.
• SHUTDOWN: the repository is no more active. Its content is saved by the ANS, and from now on, a message addressed to it will be stored in its mailbox.
• WAKE UP: the repository is reactivated. Its content is read from the ANS, and its mailbox too.
• TURN TO GROUP REPOSITORY: the repository is changed from an individual repository into a group repository.

Initiatives

Initiatives concern the CO₄ actions that can be taken by an individual repository. Once issued, they are stored in the set of initiatives of the repository. All but "evaluate" and "deny" are subject to acceptation by the other subscribers (thus require the use of a CFC).

• REGISTER The repository subscribes to another repository (see ), that will become its group repository. This can only happen if the individual repository does not already have a group repository, if the asked repository had been turned into a group repository, and if all its subscribers (if any) accept the new subscriber. Once accepted, the current repository will receive the complete content of the group repository and will have to answer all the proposals concerned by pending CFC issued by the group repository.
• EVALUATE The repository asks its group repository to evaluate a particular proposal. The answer is "unanswered" until the group repository answers by "admissible", "contained" or "contradictory" (see TEST below).
• ACHIEVE The repository asks its group repository to add a particular assertion to its content (see ).
• FORWARD The repository asks its group repository to issue a particular query. For example, forwarding a registration will cause the group repository to try to register. Forward actions can be nested.
• DENY The repository tells its group repository to cancel a previously issued query. This can only apply if the concerned CFC has not yet been accepted or rejected.

Answers

Each proposal, initiative and CFC has a status which can be (see ):

• initial state;
• (only for initiative) when the issuer denied its initiative;
• when it has been accepted;
• when it has been rejected (the reason is then provided);
• when it has been challenged (the alternative is then provided);
• when an error occurred (the error message is then provided).

• ACCEPT: the repository accepts the proposal.
• REJECT: the repository rejects the proposal. It provides a comment explaining the rejection.
• CHALLENGE: the repository accepts a part of the proposal, rejects another part and adds a new proposal to it.

Content management

Since the messages exchanged between the repository and its group repository contain some assertions, it is possible to manipulate them and to add them into its own repository content. Thus when some content is carried by a message, it is possible to apply the following actions to it (see ):

• TEST: the repository confronts the content of the message to its content. The result can be one of the following:

CONTRADICTORY when the assertion is contrary to the repository;

ADMISSIBLE when the assertion can be added to the repository.

• APPLY: the content of the message is added to the repository content.
• LOG: the content of the message is not added to the repository content. It is logged in a logbook.

Customising

There are several possibilities for modifying the default behaviour of the CO₄ protocol. These simple customisations are currently handled by environment variables considered by the system.

Under UNIX, a variable var can be turned on by typing

 	setenv var 1

	
	setenv var 0

Tracing

The default behaviour of the CO₄ protocol is silent. However, it is possible to have all the messages sent by a repository printed. This is achieved by setting the CO4_TRACE variable to 1. Each message sent is printed under the following format:

B2 --(.... W=00)-register(tcp://lotse.inrialpes.fr:5552) --> B3  [register]
                B3 --(T=00 ....)-notify(accept) --> B2

Setting CO4_TRACE to 0 will prevent the messages to appear.

Housekeeping

When a CFC, a proposal or an initiative has reached a final status, it is discarded from CO₄ data structures, to save space. Setting CO4_KEEP_ALL environment variable to 1 will keep them, while setting it to 0 will discard them (by default).

Anonymity

The default behaviour, when issuing a CFC consists in transmitting the initial proposal (containing the identification of the issuer). It is possible to mask this information during the voting process by setting the CO4_ANONYMOUS environment variable to 1. A value of 0 will show this information. This only matters in group repositories.

Automatism

An individual repository can prefer to automatically accept propositions, or to automatically accept proposals due to itself, instead of voting every time. Just setting CO4_ACCEPT_ALL or CO4_ACCEPT_MINE to 1 will make CO₄ work more automatically, while setting them to 0 will give more control to the user.

Interface

The CO₄ package contains a Web browser interface, that provides two frames, one to display CO₄ main menu, the other to display either CO₄ messages, or the repository content part. Below the various panels of the graphic user interface are presented. They concern three repositories (whose content is a knowmedge base expressed in the TROEPS system) named B1, B2 and B3. B2 is a group repository to which B1 and B3 will subscribe.

Screendump : Initial CO₄ panels. The repository B1 has no group repository. Thus it must first register to a group repository.

Screendump : After that B1 has subscribed. B3 subscribes and then receives information from its new group repository: answer to the initiative (subscription), proposals to answer and tells to integrate in its content.

Screendump : More proposals to answer will appear into B1 interface as long as B3 sends new ones.

Screendump . More and more information is communicated to the repository (B1) included new status of initiatives (ACCEPTED) and new proposals.

Screendump : The content of the repositories can be displayed in the CO₄ panel. The content is a knowledge base from the TROEPS system. One can observe the "Submit" button allowing to submit the knowledge to the group knowledge base and the name of the creator of the objects (B1) in the repository B3. Since the content of the repository can be different, ne "prenom" of the displayed object is indeed not the same.

Screendump : Configuration of an individual repository (B1). It is possible to register to a group repository or to set the various values presented above. It is also possible to access all the system primitives ("delete", "shutdown", "turn-to-group", etc.).

Screendump : Management of repositories. It is possible from the HTTP interface of a group repository to access the state of the subscriber repositories.