diff --git a/api/net/sf/briar/api/transport/InvalidConfigException.java b/api/net/sf/briar/api/transport/InvalidConfigException.java new file mode 100644 index 000000000..d2a03da63 --- /dev/null +++ b/api/net/sf/briar/api/transport/InvalidConfigException.java @@ -0,0 +1,10 @@ +package net.sf.briar.api.transport; + +/** + * Thrown by a transport plugin if the specified configuration properties are + * invalid. + */ +public class InvalidConfigException extends Exception { + + private static final long serialVersionUID = 9123332784670286454L; +} diff --git a/api/net/sf/briar/api/transport/InvalidTransportException.java b/api/net/sf/briar/api/transport/InvalidTransportException.java new file mode 100644 index 000000000..3b1d1bfb9 --- /dev/null +++ b/api/net/sf/briar/api/transport/InvalidTransportException.java @@ -0,0 +1,10 @@ +package net.sf.briar.api.transport; + +/** + * Thrown by a transport plugin if the specified transport properties are + * invalid. + */ +public class InvalidTransportException extends Exception { + + private static final long serialVersionUID = -6516979794153838108L; +} diff --git a/api/net/sf/briar/api/transport/batch/BatchTransportCallback.java b/api/net/sf/briar/api/transport/batch/BatchTransportCallback.java new file mode 100644 index 000000000..b8711fedf --- /dev/null +++ b/api/net/sf/briar/api/transport/batch/BatchTransportCallback.java @@ -0,0 +1,12 @@ +package net.sf.briar.api.transport.batch; + +/** + * An interface for receiving readers and writers created by a batch-mode + * transport plugin. + */ +public interface BatchTransportCallback { + + void readerCreated(BatchTransportReader r); + + void writerCreated(BatchTransportWriter w); +} diff --git a/api/net/sf/briar/api/transport/batch/BatchTransportPlugin.java b/api/net/sf/briar/api/transport/batch/BatchTransportPlugin.java new file mode 100644 index 000000000..2f16a40b3 --- /dev/null +++ b/api/net/sf/briar/api/transport/batch/BatchTransportPlugin.java @@ -0,0 +1,63 @@ +package net.sf.briar.api.transport.batch; + +import java.util.Map; + +import net.sf.briar.api.ContactId; +import net.sf.briar.api.transport.InvalidConfigException; +import net.sf.briar.api.transport.InvalidTransportException; + +/** + * An interface for transport plugins that do not support bidirectional, + * reliable, ordered, timely delivery of data. + */ +public interface BatchTransportPlugin { + + /** + * Initialises the plugin and returns. Any connections that are later + * established by contacts or through polling will be passed to the given + * callback. + */ + void start(Map> transports, + Map config, BatchTransportCallback c) + throws InvalidTransportException, InvalidConfigException; + + /** Updates the plugin's transport properties for the given contact. */ + void setTransports(ContactId c, Map transports) + throws InvalidTransportException; + + /** Updates the plugin's configuration properties. */ + void setConfig(Map config) throws InvalidConfigException; + + /** + * Returns true if the plugin's poll() method should be called + * periodically to attempt to establish connections. + */ + boolean shouldPoll(); + + /** + * Returns the desired interval in seconds between calls to the plugin's + * poll() method. + */ + int getPollingInterval(); + + /** + * Attempts to establish incoming and/or outgoing connections using the + * current transport and configuration properties, and passes any created + * readers and/or writers to the callback. + */ + void poll(); + + /** + * Attempts to create and return a BatchTransportReader for the given + * contact using the current transport and configuration properties. + * Returns null if a reader could not be created. + */ + BatchTransportReader createReader(ContactId c); + + /** + * Attempts to create and return a BatchTransportWriter for the given + * contact using the current transport and configuration properties. + * Returns null if a writer could not be created. + */ + BatchTransportWriter createWriter(ContactId c); +} diff --git a/api/net/sf/briar/api/transport/batch/BatchTransportReader.java b/api/net/sf/briar/api/transport/batch/BatchTransportReader.java new file mode 100644 index 000000000..7d678b398 --- /dev/null +++ b/api/net/sf/briar/api/transport/batch/BatchTransportReader.java @@ -0,0 +1,21 @@ +package net.sf.briar.api.transport.batch; + +import java.io.IOException; +import java.io.InputStream; + +/** + * An interface for reading data from a batch-mode transport. The reader is not + * responsible for decrypting or authenticating the data before returning it. + */ +public interface BatchTransportReader { + + /** Returns an input stream for reading from the transport. */ + InputStream getInputStream() throws IOException; + + /** + * Closes the reader and disposes of any associated state. This method must + * be called even if the reader is not used, or if an exception is thrown + * while using the reader. + */ + void close() throws IOException; +} diff --git a/api/net/sf/briar/api/transport/batch/BatchTransportWriter.java b/api/net/sf/briar/api/transport/batch/BatchTransportWriter.java new file mode 100644 index 000000000..2c77c3c90 --- /dev/null +++ b/api/net/sf/briar/api/transport/batch/BatchTransportWriter.java @@ -0,0 +1,24 @@ +package net.sf.briar.api.transport.batch; + +import java.io.IOException; +import java.io.OutputStream; + +/** + * An interface for writing data to a batch-mode transport. The writer is not + * responsible for authenticating or encrypting the data before writing it. + */ +public interface BatchTransportWriter { + + /** Returns the maximum number of bytes that can be written. */ + long getCapacity() throws IOException; + + /** Returns an output stream for writing to the transport. */ + OutputStream getOutputStream() throws IOException; + + /** + * Closes the writer and disposes of any associated state. This method must + * be called even if the writer is not used, or if an exception is thrown + * while using the writer. + */ + void close() throws IOException; +} diff --git a/api/net/sf/briar/api/transport/stream/StreamTransportCallback.java b/api/net/sf/briar/api/transport/stream/StreamTransportCallback.java new file mode 100644 index 000000000..7584d38d0 --- /dev/null +++ b/api/net/sf/briar/api/transport/stream/StreamTransportCallback.java @@ -0,0 +1,10 @@ +package net.sf.briar.api.transport.stream; + +/** + * An interface for receiving connections created by a stream-mode transport + * plugin. + */ +public interface StreamTransportCallback { + + void connectionCreated(StreamTransportConnection c); +} diff --git a/api/net/sf/briar/api/transport/stream/StreamTransportConnection.java b/api/net/sf/briar/api/transport/stream/StreamTransportConnection.java new file mode 100644 index 000000000..d90a45018 --- /dev/null +++ b/api/net/sf/briar/api/transport/stream/StreamTransportConnection.java @@ -0,0 +1,26 @@ +package net.sf.briar.api.transport.stream; + +import java.io.IOException; +import java.io.InputStream; +import java.io.OutputStream; + +/** + * An interface for reading and writing data over a stream-mode transport. The + * connection is not responsible for encrypting/decrypting or authenticating + * the data. + */ +public interface StreamTransportConnection { + + /** Returns an input stream for reading from the connection. */ + InputStream getInputStream() throws IOException; + + /** Returns an output stream for writing to the connection. */ + OutputStream getOutputStream() throws IOException; + + /** + * Closes the connection and disposes of any associated state. This method + * must be called even if the connection is not used, or if an exception + * is thrown while using the connection. + */ + void close() throws IOException; +} diff --git a/api/net/sf/briar/api/transport/stream/StreamTransportPlugin.java b/api/net/sf/briar/api/transport/stream/StreamTransportPlugin.java new file mode 100644 index 000000000..55ce007dd --- /dev/null +++ b/api/net/sf/briar/api/transport/stream/StreamTransportPlugin.java @@ -0,0 +1,56 @@ +package net.sf.briar.api.transport.stream; + +import java.util.Map; + +import net.sf.briar.api.ContactId; +import net.sf.briar.api.transport.InvalidConfigException; +import net.sf.briar.api.transport.InvalidTransportException; + +/** + * An interface for transport plugins that support bidirectional, reliable, + * ordered, timely delivery of data. + */ +public interface StreamTransportPlugin { + + /** + * Initialises the plugin and returns. Any connections that are later + * established by contacts or through polling will be passed to the given + * callback. + */ + void start(Map> transports, + Map config, StreamTransportCallback c) + throws InvalidTransportException, InvalidConfigException; + + /** Updates the plugin's transport properties for the given contact. */ + void setTransports(ContactId c, Map transports) + throws InvalidTransportException; + + /** Updates the plugin's configuration properties. */ + void setConfig(Map config) throws InvalidConfigException; + + /** + * Returns true if the plugin's poll() method should be called + * periodically to attempt to establish connections. + */ + boolean shouldPoll(); + + /** + * Returns the desired interval in seconds between calls to the plugin's + * poll() method. + */ + int getPollingInterval(); + + /** + * Attempts to establish connections using the current transport and + * configuration properties, and passes any created connections to the + * callback. + */ + void poll(); + + /** + * Attempts to create and return a StreamTransportConnection to the given + * contact using the current transport and configuration properties. + * Returns null if a connection could not be created. + */ + StreamTransportConnection createConnection(ContactId c); +}