org.jnetstream.protocol
Interface ProtocolLoader

public interface ProtocolLoader

A protocol loader is an object that is responsible for loading protocols. The class ProtocolLoader is an interface. Given binary or source name of a protocol, a protocol loader will attempt to load the binary file or compile the corresponding source file into binary form and load it into the runtime environment.

Every protocol object contains a reference to the ProtocolLoader that loaded it. Although more convenient methods are provided through the ProtocolRegistry methods to find and load classes.

Care must be taken to link a loaded protocol definition at an appropriate time. This is typically done by the runtime environment when all the protocol's dependencies have been loaded first. Normally protocols are linked ondemand when they are needed by decoders and dissectors.

Author:

Mark Bednarczyk, Sly Technologies, Inc.

Field Summary

static java.lang.String	PROPERTY_JAVA_CLASS_PATH
static java.lang.String	PROPERTY_NPL_PROTOCOL_PATH

Method Summary

ProtocolInfo	findLoadedProtocol(java.lang.String name) Will search only in the list of protocols that have been already defined in the ProtocolRegistry.
ProtocolInfo	findProtocol(java.lang.String name) Will search in the list of protocols that have been already defined in the ProtocolRegistry and in other places as defined by the implementation of this interface.
ProtocolLoader	getParent() Returns the parent ProtocolLoader.
java.net.URL	getResource(java.lang.String name) Method that returns a URL for the requested named resource.
java.io.InputStream	getResourceAsStream(java.lang.String name) Opens up an InputStream to the resource if found.
ProtocolInfo	linkProtocol(java.lang.String name) Links the named protocol into the runtime environment.
ProtocolInfo	loadProtocol(java.io.InputStream in, java.net.URL url) Loads a protocol definition from a user supplied stream.
ProtocolInfo	loadProtocol(java.lang.String name) Loads either the binary protocol file or invokes the compiler to compile the source protocol definition to binary form and loads it.

Field Detail

PROPERTY_NPL_PROTOCOL_PATH

static final java.lang.String PROPERTY_NPL_PROTOCOL_PATH

See Also:

Constant Field Values

PROPERTY_JAVA_CLASS_PATH

static final java.lang.String PROPERTY_JAVA_CLASS_PATH

See Also:

Constant Field Values

Method Detail

findLoadedProtocol

ProtocolInfo findLoadedProtocol(java.lang.String name)

Will search only in the list of protocols that have been already defined in the ProtocolRegistry. Will not perform an extensive search for the protocol.

Parameters:

name - name of the protocol to locate

Returns:

protocol if found, otherwise null

loadProtocol

ProtocolInfo loadProtocol(java.lang.String name)
                          throws ProtocolDeclarationException,
                                 ProtocolNotFoundException,
                                 java.io.IOException

Loads either the binary protocol file or invokes the compiler to compile the source protocol definition to binary form and loads it. Does not perform link on the protocol.

Parameters:

name - name of the protocol to load

Returns:

protocol that has been fully loaded. This method never returns null.

Throws:

ProtocolDeclarationException - if the protocol binary or source files contain some kind of delaration or syntax errors

ProtocolNotFoundException - if the protocol binary and source files can not be found

java.io.IOException - any problems with physically accessing the files

linkProtocol

ProtocolInfo linkProtocol(java.lang.String name)
                          throws ProtocolNotFoundException,
                                 ProtocolDeclarationException,
                                 java.io.IOException,
                                 ProtocolBindingException

Links the named protocol into the runtime environment. This should only be done by the runtime system at an appropriate time. If done by the user too early, unresolved link exceptions may be thrown.

Parameters:

name - name of the protocol to link

Returns:

protocol that has been fully linked. This method never returns null.

Throws:

ProtocolBindingException - Any problems during the linking process. Uresolved references, etc..

ProtocolDeclarationException - if the protocol binary or source files contain some kind of delaration or syntax errors

ProtocolNotFoundException - if the protocol binary and source files can not be found

java.io.IOException - any problems with physically accessing the files

getParent

ProtocolLoader getParent()

Returns the parent ProtocolLoader.

Returns:

Returns the parent loader or null if this is the root system loader.

getResource

java.net.URL getResource(java.lang.String name)

Method that returns a URL for the requested named resource.

Parameters:

name - name of the resource (protocol declaration, image, or anything else to search for.)

Returns:

url to the resource or null if not found

getResourceAsStream

java.io.InputStream getResourceAsStream(java.lang.String name)

Opens up an InputStream to the resource if found.

Parameters:

name - name of the resource to open

Returns:

InputStream bound to the named resource

loadProtocol

ProtocolInfo loadProtocol(java.io.InputStream in,
                          java.net.URL url)
                          throws ProtocolDeclarationException

Loads a protocol definition from a user supplied stream. The URL is required to help identify the protocol and report errors. The protocol is not linked into the environment until it is needed by the runtime environment.

Parameters:

in - Input stream to read from

url - url of the source of this stream

Returns:

protocol that has been loaded with the definition from the stream. This method never returns null.

Throws:

ProtocolDeclarationException - any syntax or declaration errors found in the definition

findProtocol

ProtocolInfo findProtocol(java.lang.String name)
                          throws ProtocolNotFoundException

Will search in the list of protocols that have been already defined in the ProtocolRegistry and in other places as defined by the implementation of this interface.

Parameters:

name - name of the protocol to locate

Returns:

protocol if found, otherwise null

Throws:

ProtocolNotFoundException