org.scion.jpan

Class ScionDatagramChannel

java.lang.Object

org.scion.jpan.ScionDatagramChannel

All Implemented Interfaces:

Closeable, AutoCloseable, ByteChannel, Channel, ReadableByteChannel, WritableByteChannel

Direct Known Subclasses:

SelectingDatagramChannel

public class ScionDatagramChannel
extends Object
implements ByteChannel, Closeable

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ScionDatagramChannel.RefreshPolicy

Field Summary

Fields

Modifier and Type	Field and Description
protected static int	DEFAULT_BUFFER_SIZE

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ScionDatagramChannel(ScionService service, DatagramChannel channel)

Method Summary

Modifier and Type	Method and Description
C	bind(InetSocketAddress address)
protected void	buildHeader(ByteBuffer buffer, Path path, int payloadLength, InternalConstants.HdrTypes hdrType)
protected DatagramChannel	channel()
protected void	checkConnected(boolean requiredState)
protected void	checkListeners(Scmp.Message scmpMsg)
protected void	checkOpen()
void	close()
void	configureBlocking(boolean block)
void	configureRemoteDispatcher(boolean hasDispatcher) Deprecated. Not required anymore, will be removed for 0.5.0
C	connect(Path path) Connect to a destination host.
C	connect(SocketAddress addr) Connect to a destination host.
void	disconnect()
protected void	ensureBound()
protected ByteBuffer	getBufferReceive(int requiredSize)
protected ByteBuffer	getBufferSend(int requiredSize)
protected int	getCfgExpirationSafetyMargin()
Path	getConnectionPath() Get the currently connected path.
protected InetSocketAddress	getFirstHopAddress(ByteBuffer buffer, InetSocketAddress srcAddress)
InetSocketAddress	getLocalAddress() Returns the local address.
protected InetAddress	getLocalAddressForSend(Path path)
protected int	getLocalPortForSend()
Path	getMappedPath(InetSocketAddress address) The channel maintains mappings from input address to output paths.
Path	getMappedPath(Path path) The channel maintains mappings from input path to output paths.
<T> T	getOption(SocketOption<T> option)
InetSocketAddress	getOverrideSourceAddress()
PathPolicy	getPathPolicy()
InetSocketAddress	getRemoteAddress() Returns the remote address.
ScionService	getService() Return the ScionService used by this channel.
boolean	isBlocking()
boolean	isConnected()
boolean	isOpen()
static ScionDatagramChannel	open() Creates a channel with the default ScionService.
static ScionDatagramChannel	open(ScionService service) Creates a channel with a specific ScionService instance.
static ScionDatagramChannel	open(ScionService service, DatagramChannel channel)
int	read(ByteBuffer dst) Read data from the connected stream.
protected ReentrantLock	readLock()
ScionSocketAddress	receive(ByteBuffer userBuffer)
protected static InternalConstants.HdrTypes	receiveExtensionHeader(ByteBuffer buffer, InternalConstants.HdrTypes hdrType)
protected ResponsePath	receiveFromChannel(ByteBuffer buffer, InternalConstants.HdrTypes expectedHdrType)
protected void	receiveScmp(ByteBuffer buffer, Path path)
int	send(ByteBuffer srcBuffer, Path path) Attempts to send the content of the buffer to the destinationAddress.
int	send(ByteBuffer srcBuffer, SocketAddress destination) Attempts to send the content of the buffer to the destinationAddress.
protected int	sendRaw(ByteBuffer buffer, Path path)
<T> C	setOption(SocketOption<T> option, T t)
void	setOverrideSourceAddress(InetSocketAddress address) This allows overriding the source address in SCION headers.
void	setPathPolicy(PathPolicy pathPolicy) Set the path policy.
Consumer<Scmp.ErrorMessage>	setScmpErrorListener(Consumer<Scmp.ErrorMessage> listener) The listener will be called for every SCMP error message that is received.
protected Object	stateLock()
protected void	updateConnection(RequestPath newPath, boolean mustBeConnected)
protected boolean	validate(ByteBuffer buffer)
int	write(ByteBuffer src) Write the content of a ByteBuffer to a connection.
protected ReentrantLock	writeLock()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.nio.channels.Channel

close, isOpen

Field Detail

DEFAULT_BUFFER_SIZE

protected static final int DEFAULT_BUFFER_SIZE

See Also:

Constant Field Values

Constructor Detail

ScionDatagramChannel

protected ScionDatagramChannel(ScionService service,
                               DatagramChannel channel)
                        throws IOException

Throws:

IOException

Method Detail

open

public static ScionDatagramChannel open()
                                 throws IOException

Creates a channel with the default ScionService.

Returns:

new channel

Throws:

IOException - in case of an error

open

public static ScionDatagramChannel open(ScionService service)
                                 throws IOException

Creates a channel with a specific ScionService instance. The instance can be 'null'.

Use of 'null' is not recommended but can be used for server side channels if no topology file is available. The ScionService is required to look up and refresh paths. It is also required to determine addresses and ports of border routers.

A server side channel (a channel that only responds to packets by reversing their path) may work without a service. However, having a service allows the server to look up the correct border router port for the first hop. If no service is available, the port is determined from the incoming IP header, assuming that the border router sends and receives on the same IP/port. Unfortunately, this is not guaranteed to be the case, so using a service to look up the correct port is recommended.

Parameters:

service - ScionService.

Returns:

new channel

Throws:

IOException - if an error occurs

open

public static ScionDatagramChannel open(ScionService service,
                                        DatagramChannel channel)
                                 throws IOException

Throws:

IOException

configureBlocking

public void configureBlocking(boolean block)
                       throws IOException

Throws:

IOException

receive

public ScionSocketAddress receive(ByteBuffer userBuffer)
                           throws IOException

Throws:

IOException

send

public int send(ByteBuffer srcBuffer,
                SocketAddress destination)
         throws IOException

Attempts to send the content of the buffer to the destinationAddress. This method will request a new path for each call.

Parameters:

srcBuffer - Data to send

destination - Destination address. This should contain a host name known to the DNS so that the ISD/AS information can be retrieved.

Returns:

The number of bytes sent, see DatagramChannel.send(ByteBuffer, SocketAddress).

Throws:

IOException - if an error occurs, e.g. if the destinationAddress is an IP address that cannot be resolved to an ISD/AS.

See Also:

DatagramChannel.send(ByteBuffer, SocketAddress)

send

public int send(ByteBuffer srcBuffer,
                Path path)
         throws IOException

Attempts to send the content of the buffer to the destinationAddress.

Parameters:

srcBuffer - Data to send

path - Path to destination. Expiration is *not* verified.

Returns:

The number of bytes sent, see DatagramChannel.send(ByteBuffer, SocketAddress).

Throws:

IOException - if an error occurs, e.g. if the destinationAddress is an IP address that cannot be resolved to an ISD/AS.

See Also:

DatagramChannel.send(ByteBuffer, SocketAddress)

read

public int read(ByteBuffer dst)
         throws IOException

Read data from the connected stream.

Specified by:

read in interface ReadableByteChannel

Parameters:

dst - The ByteBuffer that should contain data from the stream.

Returns:

The number of bytes that were read into the buffer or -1 if end of stream was reached.

Throws:

NotYetConnectedException - If the channel is not connected.

ClosedChannelException - If the channel is closed, e.g. by calling interrupt during read().

IOException - If some IOError occurs.

See Also:

DatagramChannel.read(ByteBuffer), ReadableByteChannel.read(ByteBuffer)

write

public int write(ByteBuffer src)
          throws IOException

Write the content of a ByteBuffer to a connection. This method uses the path that was provided or looked up during `connect()`. The path will automatically be refreshed when expired.

Specified by:

write in interface WritableByteChannel

Parameters:

src - The data to send

Returns:

The number of bytes written.

Throws:

NotYetConnectedException - If the channel is not connected.

ClosedChannelException - If the channel is closed.

IOException - If some IOError occurs.

See Also:

DatagramChannel.write(ByteBuffer[])

getMappedPath

public Path getMappedPath(InetSocketAddress address)

The channel maintains mappings from input address to output paths. Input addresses are given as input to send(ByteBuffer, SocketAddress). The channel tries to resolve the address via DNS TXT record to a SCION enabled address and stores the result in the mapping for future use.

Parameters:

address - A destination address

Returns:

The mapped path or the path itself if no mapping is available.

getMappedPath

public Path getMappedPath(Path path)

The channel maintains mappings from input path to output paths. Input paths are given as input to send(ByteBuffer, Path). If the path is valid, it is also used as actual path for any packet sent to the destination. If the path has expired, the channel will try to find an identical, but more recent path and store it in the mapping.

Parameters:

path - A Path

Returns:

The mapped path or the path itself if no mapping is available.

isBlocking

public boolean isBlocking()

getPathPolicy

public PathPolicy getPathPolicy()

setPathPolicy

public void setPathPolicy(PathPolicy pathPolicy)
                   throws IOException

Set the path policy. The default path policy is set in PathPolicy.DEFAULT. If the channel is connected, this method will request a new path using the new policy.

After initially setting the path policy, it is used to request a new path during write() and send() whenever a path turns out to be close to expiration.

Parameters:

pathPolicy - the new path policy

Throws:

IOException

See Also:

PathPolicy.DEFAULT

getService

public ScionService getService()

Return the ScionService used by this channel. A ScionService is, for example, required for lookup up a path from a daemon or control server. See also open(ScionService).

Returns:

the service or 'null'.

channel

protected DatagramChannel channel()

bind

public C bind(InetSocketAddress address)
       throws IOException

Throws:

IOException

ensureBound

protected void ensureBound()
                    throws IOException

Throws:

IOException

getLocalAddress

public InetSocketAddress getLocalAddress()
                                  throws IOException

Returns the local address. Note that this may change as the path changes, e.g. if we connect to a new border router on a different network interface.

Returns:

The local address.

Throws:

IOException - If an I/O error occurs

See Also:

DatagramChannel.getLocalAddress()

getRemoteAddress

public InetSocketAddress getRemoteAddress()
                                   throws IOException

Returns the remote address.

Returns:

The remote address or 'null' if this channel is not connected.

Throws:

IOException - If an I/O error occurs

See Also:

DatagramChannel.getRemoteAddress(), connect(SocketAddress), connect(Path)

disconnect

public void disconnect()
                throws IOException

Throws:

IOException

isOpen

public boolean isOpen()

close

public void close()
           throws IOException

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

IOException

connect

public C connect(SocketAddress addr)
          throws IOException

Connect to a destination host.

NB: A SCION channel will internally connect to the next border router (first hop) instead of the remote host.
If the address is an instance of ScionSocketAddress then connect will use the path associated with the address, see connect(Path).

NB: This method does internally not call DatagramChannel.connect(), instead it calls bind(). That means this method does NOT perform any additional security checks associated with connect(), only those associated with bind().

Parameters:

addr - Address of remote host.

Returns:

This channel.

Throws:

IOException - for example when the first hop (border router) cannot be connected.

connect

public C connect(Path path)
          throws IOException

Connect to a destination host. Note:
- A SCION channel will internally connect to the next border router (first hop) instead of the remote host.
- The path will be replaced with a new path once it is expired.

NB: This method does internally not call DatagramChannel.connect(SocketAddress). That means this method does NOT perform any additional security checks associated with connect(). It will however perform a `bind(null)` unless the channel is already bound.

"connect()" is understood to provide connect to a destination address (IP+port).
- send()ing packet to another destination will cause an Exception.
- packets received from a different destination will be dropped.
- connecting to a given Path only connects to the destination address, the path (route) itself may change, i.e. different border routers may be used.

Parameters:

path - Path to the remote host.

Returns:

This channel.

Throws:

IOException - for example when the first hop (border router) cannot be connected.

getConnectionPath

public Path getConnectionPath()

Get the currently connected path. The connected path is set during connect(Path) and may be refreshed when expired.

Returns:

the current Path or `null` if not path is connected.

receiveFromChannel

protected ResponsePath receiveFromChannel(ByteBuffer buffer,
                                          InternalConstants.HdrTypes expectedHdrType)
                                   throws IOException

Throws:

IOException

getFirstHopAddress

protected InetSocketAddress getFirstHopAddress(ByteBuffer buffer,
                                               InetSocketAddress srcAddress)

receiveExtensionHeader

protected static InternalConstants.HdrTypes receiveExtensionHeader(ByteBuffer buffer,
                                                                   InternalConstants.HdrTypes hdrType)

receiveScmp

protected void receiveScmp(ByteBuffer buffer,
                           Path path)

checkListeners

protected void checkListeners(Scmp.Message scmpMsg)

configureRemoteDispatcher

@Deprecated
public void configureRemoteDispatcher(boolean hasDispatcher)

Deprecated. Not required anymore, will be removed for 0.5.0

Assume that the destination host uses a dispatcher.

Calling this method sets an internal flag that forces the destination port of intra-AS packets to be 30041 independent of the UDP-overlay port. This flag has no effect for inter-AS packets or if the overlay port is already 30041.

Parameters:

hasDispatcher - Set to 'true' if remote end-host uses a dispatcher and requires using port 30041.

setOverrideSourceAddress

public void setOverrideSourceAddress(InetSocketAddress address)

This allows overriding the source address in SCION headers. This can be useful when a host is located behind a NAT. The specified source address should in this case be the external address of the NAT.

Parameters:

address - The external source address

getOverrideSourceAddress

public InetSocketAddress getOverrideSourceAddress()

getLocalAddressForSend

protected InetAddress getLocalAddressForSend(Path path)
                                      throws IOException

Throws:

IOException

getLocalPortForSend

protected int getLocalPortForSend()
                           throws IOException

Throws:

IOException

sendRaw

protected int sendRaw(ByteBuffer buffer,
                      Path path)
               throws IOException

Throws:

IOException

setScmpErrorListener

public Consumer<Scmp.ErrorMessage> setScmpErrorListener(Consumer<Scmp.ErrorMessage> listener)

The listener will be called for every SCMP error message that is received.

Parameters:

listener - A consumer for error messages. Use 'null' to deregister the listener.

Returns:

The previous registered listener, may be 'null'.

checkOpen

protected void checkOpen()
                  throws ClosedChannelException

Throws:

ClosedChannelException

checkConnected

protected void checkConnected(boolean requiredState)

isConnected

public boolean isConnected()

getOption

public <T> T getOption(SocketOption<T> option)
                throws IOException

Throws:

IOException

setOption

public <T> C setOption(SocketOption<T> option,
                       T t)
                throws IOException

Throws:

IOException

getCfgExpirationSafetyMargin

protected int getCfgExpirationSafetyMargin()

getBufferSend

protected final ByteBuffer getBufferSend(int requiredSize)

Parameters:

requiredSize - minimum required buffer size

Returns:

ByteBuffer usable for sending data.

getBufferReceive

protected final ByteBuffer getBufferReceive(int requiredSize)

Parameters:

requiredSize - minimum required buffer size

Returns:

ByteBuffer usable for receiving data.

buildHeader

protected void buildHeader(ByteBuffer buffer,
                           Path path,
                           int payloadLength,
                           InternalConstants.HdrTypes hdrType)
                    throws IOException

Parameters:

buffer - The output buffer

path - path

payloadLength - payload length

hdrType - Header type e.g. SCMP

Throws:

IOException - in case of IOException.

updateConnection

protected void updateConnection(RequestPath newPath,
                                boolean mustBeConnected)
                         throws IOException

Throws:

IOException

validate

protected boolean validate(ByteBuffer buffer)
                    throws ScionException

Throws:

ScionException

readLock

protected ReentrantLock readLock()

writeLock

protected ReentrantLock writeLock()

stateLock

protected Object stateLock()