org.ccnx.ccn.profiles.CommandMarker Class Reference

The command marker prefix allows profiles to register a namespace for commands, queries, or other special identifiers, beginning with the special prefix marker byte C1 (COMMAND_MARKER_BYTE). More...

List of all members.

Public Member Functions

byte[] getBytes ()
 Return binary representation of command marker.
int length ()
String getNamespace ()
 Returns the initial name components after the first marker of this command marker, up to the operation (if any).
String getOperation ()
 Returns the final string component operation of the prefix of this command marker, if any (see getNamespace).
byte[] addArguments (String[] arguments)
 Helper method if you just need to add arguments.
byte[] addArgument (String argument)
 Helper method if you just need to add one argument.
byte[] addBinaryData (byte[] applicationData)
 Helper method if you just need to add data.
byte[] addCCNBEncodedData (byte[] applicationData)
 Helper method if you just need to add data.
boolean isMarker (byte[] nameComponent)
 Does the prefix of this component match the command bytes of this marker?
int findMarker (ContentName name)
 Find component that contains the marker.

Static Public Member Functions

static final CommandMarker commandMarker (String namespace, String command)
static final CommandMarker commandMarker (CommandMarker namespace, String command)
static boolean isCommandComponent (byte[] commandComponent)
static CommandMarker getMarker (byte[] nameComponent)
static int argumentStart (byte[] nameComponent)
static int textArgumentStart (byte[] nameComponent)
static int binaryArgumentStart (byte[] nameComponent)
static String[] getArguments (byte[] nameComponent)
 Processing application data coming in over the wire according to generic conventions.
static boolean isCCNBApplicationData (byte[] nameComponent)
static byte[] extractApplicationData (byte[] nameComponent)

Static Public Attributes

static byte[] CCN_reserved_markers
 Reserved bytes.
static final byte COMMAND_PREFIX_BYTE = (byte)0xC1
static final byte[] COMMAND_PREFIX = {COMMAND_PREFIX_BYTE, (byte)0x2E}
 C1.
static final String COMMAND_SEPARATOR = "."
static final byte COMMAND_SEPARATOR_BYTE = COMMAND_SEPARATOR.getBytes()[0]
static final String UTF8_ARGUMENT_SEPARATOR = "~"
static final byte UTF8_ARGUMENT_SEPARATOR_BYTE = UTF8_ARGUMENT_SEPARATOR.getBytes()[0]
static final byte BINARY_ARGUMENT_SEPARATOR = 0x00
static final byte CCNB_ARGUMENT_SEPARATOR = (byte)0xC1
static final String ENUMERATION_NAMESPACE = "E"
 (Name) enumeration "marker"
static final CommandMarker COMMAND_MARKER_BASIC_ENUMERATION
 Basic enumeration command, no arguments,.
static final String REPOSITORY_NAMESPACE = "R"
 Repository "marker".
static final CommandMarker COMMAND_MARKER_REPO_START_WRITE
 Start write command.
static final CommandMarker COMMAND_MARKER_REPO_CHECKED_START_WRITE
 Checked Start Write: request storage of particular stream if not already held The name prefix before the command marker component is the base name The component after the command marker is a nonce The next component is the starting segment component The next and final component is the starting segment digest component explicitly The command marker is in the middle so that the response from repo is not a data object having another data object full name (digest included) as prefix of its name.
static final CommandMarker COMMAND_MARKER_REPO_ADD_FILE
static final String NONCE_NAMESPACE = "N"
 Some very simple markers that need no other support.
static final CommandMarker COMMAND_MARKER_NONCE = commandMarker(NONCE_NAMESPACE, null)
static final String MARKER_NAMESPACE = "M"
 Marker for typed binary name components.
static final CommandMarker COMMAND_MARKER_GUID = commandMarker(CommandMarker.MARKER_NAMESPACE, "G")
 GUID marker.
static final CommandMarker COMMAND_MARKER_SCOPE
 Marker for a name component that is supposed to indicate a scope.

Protected Member Functions

 CommandMarker (CommandMarker parent, String operation)
 CommandMarker (String namespace, String command)
 CommandMarker (byte[] nameComponent)
byte[] addArgumentsAndData (String[] arguments, byte[] applicationData, byte dataMarker)
 Generate a name component that adds arguments and data to this command marker.

Protected Attributes

byte[] _byteCommandMarker
 This in practice might be only the prefix, with additional variable arguments added on the fly.

Detailed Description

The command marker prefix allows profiles to register a namespace for commands, queries, or other special identifiers, beginning with the special prefix marker byte C1 (COMMAND_MARKER_BYTE).

This class contains operations for representing and storing command marker prefixes (without arguments or application data). The CommandComponent class handles full component markers containing arguments and data.

Commands are separated into namespaces, which are UTF-8 strings, followed by an operation, which is a UTF-8 string component following the last "." in the namespace designation. (The "operation" can also just be considered the last component of the namespace.) The remainder of the command name component is interpreted by the namespace owner in whatever manner they choose, with an optional convention to separate (optional) text arguments from the namespace and operation (and each other) with the tilde character (~), and a single binary argument (which must come last) which must be prefixed with 00 for a raw binary argument, or C1 for an argument which is CCNB-encoded data. (Multiple binary arguments can be provided using CCNB-encoding.)

The namespace designation can contain "." (and so can be broken down by reverse DNS name, as with Java), " ", and other legal UTF-8 characters. It ends either with the last ., or at the end of the name component, whichever comes last. Namespaces containing only capital letters are reserved for CCN itself, and are listed here.

We consider the initial marker byte/namespace/operation component as the "command marker" and the remainder as arguments (the former refers to a fixed operation, while the latter may vary across calls to that operation). Methods to parse a name component encountered in processing either hand back a CommandMarker representing the namespace/operation, or the arguments; we don't put the arguments into a CommandMarker object.

Examples:

The repository uses a command namespace of "R", and commands like: start_write: C1.R.sw (where R is the namespace marker, sw is the specific command, and it takes no arguments)

C1.org.ccnx.frobnicate~1~37 would be a command in the namespace "org.ccnx", where the command is "frobnicate", which takes two arguments, in this case 1 and 37

The nonce protocol has only one operation, generating a nonce, with a random binary argument. C1.N00<binary argument>="">

A namespace org.ccnx.foo could have an operation bar, that took a single ccnb-encoded argument: C1.org.ccnx.foo.barC1<argument>

or 2 UTF-8 arguments and a binary argument C1.org.ccnx.foo.bar~arg1~arg100<binary argument>="">

For now put the built-in commands here as well, though as we get ones that take arguments we should start to break them out to profile-specific locations. But start simple.

Author:
rasmusse, smetters

Member Function Documentation

byte [] org.ccnx.ccn.profiles.CommandMarker.addArguments ( String[]  arguments  ) 

Helper method if you just need to add arguments.

Parameters:
arguments 
Returns:
byte [] org.ccnx.ccn.profiles.CommandMarker.addArgumentsAndData ( String[]  arguments,
byte[]  applicationData,
byte  dataMarker 
) [protected]

Generate a name component that adds arguments and data to this command marker.

See addArguments and addData if you only need to add one and not the other.

Parameters:
arguments 
applicationData 
Returns:
the name component to use containing the command marker and arguments
byte [] org.ccnx.ccn.profiles.CommandMarker.addBinaryData ( byte[]  applicationData  ) 

Helper method if you just need to add data.

Parameters:
applicationData -- raw binary
Returns:
byte [] org.ccnx.ccn.profiles.CommandMarker.addCCNBEncodedData ( byte[]  applicationData  ) 

Helper method if you just need to add data.

Parameters:
applicationData -- ccnb encoded
Returns:
int org.ccnx.ccn.profiles.CommandMarker.findMarker ( ContentName  name  ) 

Find component that contains the marker.

Parameters:
name 
Returns:
static String [] org.ccnx.ccn.profiles.CommandMarker.getArguments ( byte[]  nameComponent  )  [static]

Processing application data coming in over the wire according to generic conventions.

Particular markers can instantiate subclasses of CommandMarker to do more specific processing, or can put that processing in their profiles.

Here we put generic argument processing and command marker parsing capabilities for CMs that follow conventions. Extract any arguments associated with this prefix.

Parameters:
nameComponent 
Returns:
null if no arguments, otherwise String [] of text arguments.
byte [] org.ccnx.ccn.profiles.CommandMarker.getBytes (  ) 

Return binary representation of command marker.

Returns:
String org.ccnx.ccn.profiles.CommandMarker.getNamespace (  ) 

Returns the initial name components after the first marker of this command marker, up to the operation (if any).

Terminating "." is stripped. If there is only one initial string component, the operation is interpreted as empty, and that component is returned as the namespace. We assume we don't have any arguments in our byte array.

Returns:
boolean org.ccnx.ccn.profiles.CommandMarker.isMarker ( byte[]  nameComponent  ) 

Does the prefix of this component match the command bytes of this marker?

Returns:

Member Data Documentation

Initial value:
 { (byte)0xC0, (byte)0xC1, (byte)0xF5, 
        (byte)0xF6, (byte)0xF7, (byte)0xF8, (byte)0xF9, (byte)0xFA, (byte)0xFB, (byte)0xFC, 
        (byte)0xFD, (byte)0xFE}

Reserved bytes.

Initial value:
 
                                        commandMarker(ENUMERATION_NAMESPACE, "be")

Basic enumeration command, no arguments,.

final CommandMarker org.ccnx.ccn.profiles.CommandMarker.COMMAND_MARKER_REPO_ADD_FILE [static]
Initial value:
 
                commandMarker(REPOSITORY_NAMESPACE, "af")
Initial value:
 
                commandMarker(REPOSITORY_NAMESPACE, "sw-c")

Checked Start Write: request storage of particular stream if not already held The name prefix before the command marker component is the base name The component after the command marker is a nonce The next component is the starting segment component The next and final component is the starting segment digest component explicitly The command marker is in the middle so that the response from repo is not a data object having another data object full name (digest included) as prefix of its name.

Initial value:
 
                commandMarker(REPOSITORY_NAMESPACE, "sw")

Start write command.

Initial value:
 
                CommandMarker.commandMarker(CommandMarker.MARKER_NAMESPACE, "S")

Marker for a name component that is supposed to indicate a scope.

Marker for typed binary name components.

These aren't general binary name components, but name components with defined semantics. Specific examples are defined in their own profiles, see KeyProfile and GuidProfile, as well as markers for access controls. The interpretation of these should be a) you shouldn't show them to a user unless you really have to, and b) the content of the marker tells you the type and interpretation of the value.

Save "B" for general binary name components if we need to go there; use M for marker. Start by trying to define them in their own profiles; might have to centralize here for reference.

Some very simple markers that need no other support.

See KeyProfile and MetadataProfile for related core markers that use the Marker namespace. Nonce marker


The documentation for this class was generated from the following file:
Generated on Fri May 13 16:27:46 2011 for Content-Centric Networking in Java by  doxygen 1.6.3