Module org.newsclub.net.unix

Package org.newsclub.net.unix

Class AFTIPCSocketAddress

java.lang.Object

java.net.SocketAddress

java.net.InetSocketAddress

org.newsclub.net.unix.AFSocketAddress

org.newsclub.net.unix.AFTIPCSocketAddress

All Implemented Interfaces:

Serializable

public final class AFTIPCSocketAddress
extends AFSocketAddress

An AFSocketAddress for TIPC sockets. The TIPC socket API provides three different address types:

• Service Address.

  This address type consists of a 32-bit service type identifier and a 32-bit service instance identifier.

  The type identifier is typically determined and hard-coded by the user application programmer, but its value may have to be coordinated with other applications which might be present in the same cluster. The instance identifier is often calculated by the program, based on application specific criteria.

  Typical invocation: ofService(int, int).

• Service Range.

  This address type represents a range of service addresses of the same type and with instances between a lower and an upper range limit.

  By binding a socket to this address type one can make it represent many instances, something which has proved useful in many cases. This address type is also used as multicast address.

  Typical invocation: ofServiceRange(int, int, int).

• Socket Address.

  This address is a reference to a specific socket in the cluster.

  It contains a 32-bit port number and a 32-bit node hash number. The port number is generated by the system when the socket is created, and the node hash is generated from the corresponding node identity.

  An address of this type can be used for connecting or for sending messages in the same way as service addresses can be used, but is only valid as long as the referenced socket exists.

  Typical invocation: ofSocket(int, int).

When binding a socket to a service address or address range, the visibility scope of the binding must be indicated. There are two options, AFTIPCSocketAddress.Scope.SCOPE_NODE if the user only wants node local visibility, and AFTIPCSocketAddress.Scope.SCOPE_CLUSTER if he wants cluster global visibility. There are almost no limitations to how sockets can be bound to service addresses: one socket can be bound to many addresses or ranges, and many sockets can be bound to the same address or range.

The service types 0 through 63 are however reserved for system internal use, and are not available for user space applications.

When sending a message by service address the sender may indicate a lookup domain, also called lookup scope. This is a node hash number, limiting the set of eligible destination sockets to the indicated node. If this value is zero, all matching sockets in the whole cluster, as visible from the source node, are eligible.

Author:

Christian Kohlschütter (documentation credits to Jon Maloy and the TIPC team).

See Also:

• Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	AFTIPCSocketAddress.AddressType	The TIPC address type.
static final class	AFTIPCSocketAddress.Scope	The TIPC visibility scope.

Nested classes/interfaces inherited from class org.newsclub.net.unix.AFSocketAddress

AFSocketAddress.AFSocketAddressConstructor<T extends AFSocketAddress>

Field Summary

Fields

Modifier and Type	Field	Description
static final int	TIPC_RESERVED_TYPES	The lowest user-publishable name type.
static final int	TIPC_TOP_SRV	The "topology" service name type.

Method Summary

Modifier and Type	Method	Description
static AFAddressFamily<AFTIPCSocketAddress>	addressFamily()	Returns the corresponding AFAddressFamily.
File	getFile()	Returns the File corresponding with this address, if possible.
AFTIPCSocketAddress.Scope	getScope()	Returns the scope of this address.
int	getTIPCDomain()	Returns the TIPC domain part of this address.
int	getTIPCInstance()	Returns the TIPC instance part of this address.
int	getTIPCLower()	Returns the TIPC lower instance of this address.
int	getTIPCNodeHash()	Returns the TIPC node hash of this address.
int	getTIPCRef()	Returns the TIPC ref of this address.
int	getTIPCType()	Returns the TIPC type part of this address.
int	getTIPCUpper()	Returns the TIPC upper instance of this address.
boolean	hasFilename()	Checks if the address can be resolved to a File.
static boolean	isSupportedAddress(InetAddress addr)	Checks if an InetAddress can be unwrapped to an AFTIPCSocketAddress.
static boolean	isSupportedAddress(SocketAddress addr)	Checks if a SocketAddress can be unwrapped to an AFTIPCSocketAddress.
static AFTIPCSocketAddress	of(URI uri)	Returns an AFTIPCSocketAddress for the given URI, if possible.
static AFTIPCSocketAddress	of(URI uri, int overridePort)	Returns an AFTIPCSocketAddress for the given URI, if possible.
static AFTIPCSocketAddress	ofService(int type, int instance)	Returns an AFTIPCSocketAddress that refers to a given service type and instance, implicitly using cluster scope (AFTIPCSocketAddress.Scope.SCOPE_CLUSTER).
static AFTIPCSocketAddress	ofService(int javaPort, AFTIPCSocketAddress.Scope scope, int type, int instance, int domain)	Returns an AFTIPCSocketAddress that refers to a given service type and instance, using the given scope and the given lookup domain.
static AFTIPCSocketAddress	ofService(AFTIPCSocketAddress.Scope scope, int type, int instance)	Returns an AFTIPCSocketAddress that refers to a given service type and instance, using the given scope.
static AFTIPCSocketAddress	ofService(AFTIPCSocketAddress.Scope scope, int type, int instance, int domain)	Returns an AFTIPCSocketAddress that refers to a given service type and instance, using the given scope and the given lookup domain.
static AFTIPCSocketAddress	ofServiceRange(int type, int lower, int upper)	Returns an AFTIPCSocketAddress that refers to a given service range type and instance boundaries (lower/upper values), implicitly using cluster scope (AFTIPCSocketAddress.Scope.SCOPE_CLUSTER).
static AFTIPCSocketAddress	ofServiceRange(int javaPort, AFTIPCSocketAddress.Scope scope, int type, int lower, int upper)	Returns an AFTIPCSocketAddress that refers to a given service range type and instance boundaries (lower/upper values), implicitly using cluster scope (AFTIPCSocketAddress.Scope.SCOPE_CLUSTER).
static AFTIPCSocketAddress	ofServiceRange(AFTIPCSocketAddress.Scope scope, int type, int lower, int upper)	Returns an AFTIPCSocketAddress that refers to a given service range type and instance boundaries (lower/upper values), using the given scope.
static AFTIPCSocketAddress	ofSocket(int ref, int node)	Returns an AFTIPCSocketAddress that refers to a given TIPC socket address (i.e., referring to a particular socket instance instead of a service address).
static AFTIPCSocketAddress	ofSocket(int javaPort, int ref, int node)	Returns an AFTIPCSocketAddress that refers to a given TIPC socket address (i.e., referring to a particular socket instance instead of a service address).
static AFTIPCSocketAddress	ofTopologyService()	Returns an AFTIPCSocketAddress that refers to the topology service.
String	toString()
URI	toURI(String scheme, URI template)	Tries to create a URI based on this AFSocketAddress.
static AFTIPCSocketAddress	unwrap(String hostname, int port)	Returns an AFTIPCSocketAddress given a special InetAddress hostname that encodes the byte sequence of an AF_TIPC socket address, like those returned by AFSocketAddress.wrapAddress().
static AFTIPCSocketAddress	unwrap(InetAddress address, int port)	Returns an AFTIPCSocketAddress given a special InetAddress that encodes the byte sequence of an AF_TIPC socket address, like those returned by AFSocketAddress.wrapAddress().
static AFTIPCSocketAddress	unwrap(SocketAddress address)	Returns an AFTIPCSocketAddress given a generic SocketAddress.

Methods inherited from class org.newsclub.net.unix.AFSocketAddress

canMap, canMap, covers, getAddressFamily, getBytes, getInetAddress, getInetAddress, getInetAddress, getSocketAddress, isSupportedAddress, isUseDeserializationForInit, mapOrFail, mapOrFail, newBoundServerSocket, newConnectedSocket, newDeserializedAFSocketAddress, newForceBoundServerSocket, parseUnsignedInt, resolveAddress, toSocatAddressString, unwrap, unwrap, wrapAddress, writeNativeAddressTo

Methods inherited from class java.net.InetSocketAddress

createUnresolved, equals, getAddress, getHostName, getHostString, getPort, hashCode, isUnresolved

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Details

TIPC_TOP_SRV

public static final int TIPC_TOP_SRV

The "topology" service name type.

See Also:

• Constant Field Values

TIPC_RESERVED_TYPES

public static final int TIPC_RESERVED_TYPES

The lowest user-publishable name type.

See Also:

• Constant Field Values

Method Details

ofService

public static AFTIPCSocketAddress ofService(AFTIPCSocketAddress.Scope scope,
 int type,
 int instance)
                                     throws SocketException

Returns an AFTIPCSocketAddress that refers to a given service type and instance, using the given scope.

Parameters:

scope - The address scope.

type - The service type (0-63 are reserved).

instance - The service instance ID.

Returns:

A corresponding AFTIPCSocketAddress instance.

Throws:

SocketException - if the operation fails.

ofService

public static AFTIPCSocketAddress ofService(int type,
 int instance)
                                     throws SocketException

Returns an AFTIPCSocketAddress that refers to a given service type and instance, implicitly using cluster scope (AFTIPCSocketAddress.Scope.SCOPE_CLUSTER).

Parameters:

type - The service type (0-63 are reserved).

instance - The service instance ID.

Returns:

A corresponding AFTIPCSocketAddress instance.

Throws:

SocketException - if the operation fails.

ofService

public static AFTIPCSocketAddress ofService(AFTIPCSocketAddress.Scope scope,
 int type,
 int instance,
 int domain)
                                     throws SocketException

Returns an AFTIPCSocketAddress that refers to a given service type and instance, using the given scope and the given lookup domain.

Parameters:

scope - The address scope.

type - The service type (0-63 are reserved).

instance - The service instance ID.

domain - The lookup domain. 0 indicates cluster global lookup, otherwise a node hash, indicating that lookup should be performed only on that node

Returns:

A corresponding AFTIPCSocketAddress instance.

Throws:

SocketException - if the operation fails.

ofService

public static AFTIPCSocketAddress ofService(int javaPort,
 AFTIPCSocketAddress.Scope scope,
 int type,
 int instance,
 int domain)
                                     throws SocketException

Returns an AFTIPCSocketAddress that refers to a given service type and instance, using the given scope and the given lookup domain. A Java-only "IP port number" is stored along the instance for compatibility reasons.

Parameters:

javaPort - The emulated "port" number (not part of TIPC).

scope - The address scope.

type - The service type (0-63 are reserved).

instance - The service instance ID.

domain - The lookup domain. 0 indicates cluster global lookup, otherwise a node hash, indicating that lookup should be performed only on that node

Returns:

A corresponding AFTIPCSocketAddress instance.

Throws:

SocketException - if the operation fails.

ofServiceRange

public static AFTIPCSocketAddress ofServiceRange(AFTIPCSocketAddress.Scope scope,
 int type,
 int lower,
 int upper)
                                          throws SocketException

Returns an AFTIPCSocketAddress that refers to a given service range type and instance boundaries (lower/upper values), using the given scope.

Parameters:

scope - The address scope.

type - The service type (0-63 are reserved).

lower - Lower end of service instance ID range.

upper - Upper end of service instance ID range.

Returns:

A corresponding AFTIPCSocketAddress instance.

Throws:

SocketException - if the operation fails.

ofServiceRange

public static AFTIPCSocketAddress ofServiceRange(int type,
 int lower,
 int upper)
                                          throws SocketException

Returns an AFTIPCSocketAddress that refers to a given service range type and instance boundaries (lower/upper values), implicitly using cluster scope (AFTIPCSocketAddress.Scope.SCOPE_CLUSTER).

Parameters:

type - The service type (0-63 are reserved).

lower - Lower end of service instance ID range.

upper - Upper end of service instance ID range.

Returns:

A corresponding AFTIPCSocketAddress instance.

Throws:

SocketException - if the operation fails.

ofServiceRange

public static AFTIPCSocketAddress ofServiceRange(int javaPort,
 AFTIPCSocketAddress.Scope scope,
 int type,
 int lower,
 int upper)
                                          throws SocketException

Returns an AFTIPCSocketAddress that refers to a given service range type and instance boundaries (lower/upper values), implicitly using cluster scope (AFTIPCSocketAddress.Scope.SCOPE_CLUSTER). A Java-only "IP port number" is stored along the instance for compatibility reasons.

Parameters:

javaPort - The emulated "port" number (not part of TIPC).

scope - The address scope.

type - The service type (0-63 are reserved).

lower - Lower end of service instance ID range.

upper - Upper end of service instance ID range.

Returns:

A corresponding AFTIPCSocketAddress instance.

Throws:

SocketException - if the operation fails.

ofSocket

public static AFTIPCSocketAddress ofSocket(int ref,
 int node)
                                    throws SocketException

Returns an AFTIPCSocketAddress that refers to a given TIPC socket address (i.e., referring to a particular socket instance instead of a service address).

Parameters:

ref - 32-bit port reference ID (not to be confused with the InetSocketAddress.getPort() port).

node - Node hash number (can be used as lookup domain with ofService(Scope, int, int, int)).

Returns:

A corresponding AFTIPCSocketAddress instance.

Throws:

SocketException - if the operation fails.

ofSocket

public static AFTIPCSocketAddress ofSocket(int javaPort,
 int ref,
 int node)
                                    throws SocketException

Returns an AFTIPCSocketAddress that refers to a given TIPC socket address (i.e., referring to a particular socket instance instead of a service address). A Java-only "IP port number" is stored along the instance for compatibility reasons.

Parameters:

javaPort - The emulated "port" number (not part of TIPC).

ref - 32-bit port reference ID (not to be confused with the InetSocketAddress.getPort() port).

node - Node hash number (can be used as lookup domain with ofService(Scope, int, int, int)).

Returns:

A corresponding AFTIPCSocketAddress instance.

Throws:

SocketException - if the operation fails.

ofTopologyService

public static AFTIPCSocketAddress ofTopologyService()
                                             throws SocketException

Returns an AFTIPCSocketAddress that refers to the topology service.

Returns:

A corresponding AFTIPCSocketAddress instance.

Throws:

SocketException - if the operation fails.

unwrap

public static AFTIPCSocketAddress unwrap(InetAddress address,
 int port)
                                  throws SocketException

Returns an AFTIPCSocketAddress given a special InetAddress that encodes the byte sequence of an AF_TIPC socket address, like those returned by AFSocketAddress.wrapAddress().

Parameters:

address - The "special" InetAddress.

port - The port (use 0 for "none").

Returns:

The AFTIPCSocketAddress instance.

Throws:

SocketException - if the operation fails, for example when an unsupported address is specified.

unwrap

public static AFTIPCSocketAddress unwrap(String hostname,
 int port)
                                  throws SocketException

Returns an AFTIPCSocketAddress given a special InetAddress hostname that encodes the byte sequence of an AF_TIPC socket address, like those returned by AFSocketAddress.wrapAddress().

Parameters:

hostname - The "special" hostname, as provided by InetAddress.getHostName().

port - The port (use 0 for "none").

Returns:

The AFTIPCSocketAddress instance.

Throws:

SocketException - if the operation fails, for example when an unsupported address is specified.

unwrap

public static AFTIPCSocketAddress unwrap(SocketAddress address)
                                  throws SocketException

Returns an AFTIPCSocketAddress given a generic SocketAddress.

Parameters:

address - The address to unwrap.

Returns:

The AFTIPCSocketAddress instance.

Throws:

SocketException - if the operation fails, for example when an unsupported address is specified.

getScope

public AFTIPCSocketAddress.Scope getScope()

Returns the scope of this address.

Returns:

The scope.

getTIPCType

public int getTIPCType()

Returns the TIPC type part of this address.

Returns:

The type identifier

getTIPCInstance

public int getTIPCInstance()

Returns the TIPC instance part of this address.

Returns:

The instance identifier.

getTIPCDomain

public int getTIPCDomain()

Returns the TIPC domain part of this address.

Returns:

The domain identifier.

getTIPCLower

public int getTIPCLower()

Returns the TIPC lower instance of this address.

Returns:

The lower instance identifier.

getTIPCUpper

public int getTIPCUpper()

Returns the TIPC upper instance of this address.

Returns:

The lower instance identifier.

getTIPCRef

public int getTIPCRef()

Returns the TIPC ref of this address.

Returns:

The ref identifier.

getTIPCNodeHash

public int getTIPCNodeHash()

Returns the TIPC node hash of this address.

Returns:

The node hash.

toString

public String toString()

Overrides:

toString in class InetSocketAddress

hasFilename

public boolean hasFilename()

Description copied from class: AFSocketAddress

Checks if the address can be resolved to a File.

Specified by:

hasFilename in class AFSocketAddress

Returns:

true if the address has a filename.

getFile

public File getFile()
             throws FileNotFoundException

Description copied from class: AFSocketAddress

Returns the File corresponding with this address, if possible. A FileNotFoundException is thrown if there is no filename associated with the address, which applies to addresses in the abstract namespace, for example.

Specified by:

getFile in class AFSocketAddress

Returns:

The filename.

Throws:

FileNotFoundException - if the address is not associated with a filename.

isSupportedAddress

public static boolean isSupportedAddress(InetAddress addr)

Checks if an InetAddress can be unwrapped to an AFTIPCSocketAddress.

Parameters:

addr - The instance to check.

Returns:

true if so.

See Also:

• AFSocketAddress.wrapAddress()
• unwrap(InetAddress, int)

isSupportedAddress

public static boolean isSupportedAddress(SocketAddress addr)

Checks if a SocketAddress can be unwrapped to an AFTIPCSocketAddress.

Parameters:

addr - The instance to check.

Returns:

true if so.

See Also:

• unwrap(InetAddress, int)

addressFamily

public static AFAddressFamily<AFTIPCSocketAddress> addressFamily()

Returns the corresponding AFAddressFamily.

Returns:

The address family instance.

of

public static AFTIPCSocketAddress of(URI uri)
                              throws SocketException

Returns an AFTIPCSocketAddress for the given URI, if possible.

Parameters:

uri - The URI.

Returns:

The address.

Throws:

SocketException - if the operation fails.

of

public static AFTIPCSocketAddress of(URI uri,
 int overridePort)
                              throws SocketException

Returns an AFTIPCSocketAddress for the given URI, if possible.

Parameters:

uri - The URI.

overridePort - The port to forcibly use, or -1 for "don't override".

Returns:

The address.

Throws:

SocketException - if the operation fails.

toURI

public URI toURI(String scheme,
 URI template)
          throws IOException

Description copied from class: AFSocketAddress

Tries to create a URI based on this AFSocketAddress.

Overrides:

toURI in class AFSocketAddress

Parameters:

scheme - The target scheme.

template - An optional template to reuse certain parameters (e.g., the "path" component for an http request), or null.

Returns:

The URI.

Throws:

IOException - on error.