org.elastos.carrier

Class Carrier

java.lang.Object

org.elastos.carrier.Carrier

public class Carrier
extends java.lang.Object

The class representing Carrier node instance.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Carrier.Options Options defines several settings that control the way the Carrier node connects to the carrier network.

Field Summary

Fields

Modifier and Type	Field and Description
static int	CARRIER_MAX_USER_NAME_LEN Carrier App message max length.
static int	MAX_ID_LEN Max Carrier ID length.
static int	MAX_KEY_LEN Max Carrier KEY length.

Method Summary

Modifier and Type	Method and Description
void	acceptFriend(java.lang.String userId) Accept the friend request.
void	addFriend(java.lang.String address, java.lang.String hello) Add friend by sending a new friend request.
static Carrier	createInstance(Carrier.Options options, CarrierHandler handler) Create node instance.
protected void	finalize()
java.lang.String	getAddress() Get node address associated with the carrier node instance.
FriendInfo	getFriend(java.lang.String userId) Get specified friend information.
java.util.List<FriendInfo>	getFriends() Get friends list.
java.util.Collection<Group>	getGroups() Get groups in the Carrier instance.
static java.lang.String	getIdFromAddress(java.lang.String address) Get carrier ID from carrier node address.
java.lang.String	getNodeId() Get nodeid associated with the carrier node instance.
int	getNospam() \~Egnlish Get the nospam for Carrier address.
PresenceStatus	getPresence() Get self presence status.
UserInfo	getSelfInfo() Get self user information.
java.lang.String	getUserId() Get userid associated with the carrier node instance.
static java.lang.String	getVersion() Get current version of Carrier node.
Group	groupJoin(java.lang.String friendId, byte[] cookie) Join a group associating with cookie into which remote friend invites.
void	groupLeave(Group group) Leave a group.
void	inviteFriend(java.lang.String to, java.lang.String data, FriendInviteResponseHandler handler) Send invite request to a friend.
boolean	isFriend(java.lang.String userId) Check if the user ID is friend.
boolean	isReady() \~English Check if carrier node instance is being ready.
static boolean	isValidAddress(java.lang.String address) Check if the carrier node address is valid.
static boolean	isValidId(java.lang.String id) Check if the ID is Carrier node id.
void	kill() Disconnect carrier node from carrier network, and destroy all associated resources to carreier node instance.
void	labelFriend(java.lang.String userId, java.lang.String label) Set the label of the specified friend.
Group	newGroup() Create a new group.
void	removeFriend(java.lang.String userId) Remove a friend.
void	replyFriendInvite(java.lang.String to, int status, java.lang.String reason, java.lang.String data) Reply the friend invite request.
long	sendFriendMessage(java.lang.String to, byte[] message, FriendMessageReceiptHandler handler) Send a message to a friend.
long	sendFriendMessage(java.lang.String to, java.lang.String message, FriendMessageReceiptHandler handler) Send a message to a friend.
void	setNospam(int nospam) Update self nospam of address for this carrier node.
void	setPresence(PresenceStatus presence) Update self presence status.
void	setSelfInfo(UserInfo userinfo) Update self user information.
void	start(int iterateInterval) Start carrier node asynchronously to connect to carrier network.

Methods inherited from class java.lang.Object

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

Field Detail

MAX_ID_LEN

public static final int MAX_ID_LEN

Max Carrier ID length.

See Also:

Constant Field Values

MAX_KEY_LEN

public static final int MAX_KEY_LEN

Max Carrier KEY length.

See Also:

Constant Field Values

CARRIER_MAX_USER_NAME_LEN

public static final int CARRIER_MAX_USER_NAME_LEN

Carrier App message max length.

See Also:

Constant Field Values

Method Detail

getVersion

public static java.lang.String getVersion()

Get current version of Carrier node.

Returns:

The version of carrier node.

isValidId

public static boolean isValidId(java.lang.String id)

Check if the ID is Carrier node id.

Parameters:

id - The carrier node id to be check.

Returns:

True if id is valid, otherwise false.

isValidAddress

public static boolean isValidAddress(java.lang.String address)

Check if the carrier node address is valid.

Parameters:

address - The carrier node address to be check.

Returns:

True if key is valid, otherwise false.

getIdFromAddress

public static java.lang.String getIdFromAddress(java.lang.String address)

Get carrier ID from carrier node address.

Parameters:

address - The carrier node address.

Returns:

User id if address is valid, otherwise null

createInstance

public static Carrier createInstance(Carrier.Options options,
                                     CarrierHandler handler)
                              throws CarrierException

Create node instance. After returning, it's ready to start and therefore connect to carrier network.

Parameters:

options - The options to set for creating carrier node.

handler - The interface handler for carrier node.

Returns:

New Carrier instance

Throws:

CarrierException - carrier exception.

finalize

protected void finalize()
                 throws java.lang.Throwable

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable

start

public void start(int iterateInterval)

Start carrier node asynchronously to connect to carrier network. If the connection to network is successful, carrier node starts working.

Parameters:

iterateInterval - Internal loop interval, in milliseconds.

kill

public void kill()

Disconnect carrier node from carrier network, and destroy all associated resources to carreier node instance. After calling the method, the carrier node instance becomes invalid.

getAddress

public java.lang.String getAddress()
                            throws CarrierException

Get node address associated with the carrier node instance.

Returns:

the node address.

Throws:

CarrierException - carrier exception.

getNodeId

public java.lang.String getNodeId()
                           throws CarrierException

Get nodeid associated with the carrier node instance.

Returns:

the nodeid.

Throws:

CarrierException - carrier exception.

getUserId

public java.lang.String getUserId()
                           throws CarrierException

Get userid associated with the carrier node instance.

Returns:

the userid.

Throws:

CarrierException - carrier exception.

setNospam

public void setNospam(int nospam)
               throws CarrierException

Update self nospam of address for this carrier node. Update the nospam of carrier node address with host byte order expected. Nospam for Carrier address is used to eliminate spam friend request.

Parameters:

nospam - An integer value.

Throws:

CarrierException - carrier exception.

getNospam

public int getNospam()
              throws CarrierException

\~Egnlish Get the nospam for Carrier address. Get the 4-byte nospam part of the Carrier address with host byte order expected. Nospam for Carrier address is used to eliminate spam friend request.

Returns:

the nospam for Carrier address.

Throws:

CarrierException - carrier exception.

setSelfInfo

public void setSelfInfo(UserInfo userinfo)
                 throws CarrierException

Update self user information. After self user information changed, carrier node will update this information to carrier network, and thereupon network broadcasts the change to all friends.

Parameters:

userinfo - The user information to update for this carrier node.

Throws:

java.lang.IllegalArgumentException - illegal exception.

CarrierException - carrier exception.

getSelfInfo

public UserInfo getSelfInfo()
                     throws CarrierException

Get self user information.

Returns:

the user information to the carrier node.

Throws:

CarrierException - carrier exception.

setPresence

public void setPresence(PresenceStatus presence)
                 throws CarrierException

Update self presence status.

Parameters:

presence - the new presence status.

Throws:

java.lang.IllegalArgumentException - illegal exception.

CarrierException - carrier exception.

getPresence

public PresenceStatus getPresence()
                           throws CarrierException

Get self presence status.

Returns:

self presence status

Throws:

CarrierException - carrier exception.

isReady

public boolean isReady()

\~English Check if carrier node instance is being ready. All carrier interactive APIs should be called only if carrier node instance is being ready.

Returns:

true if the carrier node instance is ready, or false if not.

getFriends

public java.util.List<FriendInfo> getFriends()
                                      throws CarrierException

Get friends list.

Returns:

The list of friend information to current user

Throws:

CarrierException - carrier exception.

getFriend

public FriendInfo getFriend(java.lang.String userId)
                     throws CarrierException

Get specified friend information.

Parameters:

userId - The user identifier of friend

Returns:

The friend information.

Throws:

java.lang.IllegalArgumentException - illegal exception.

CarrierException - carrier exception.

labelFriend

public void labelFriend(java.lang.String userId,
                        java.lang.String label)
                 throws CarrierException

Set the label of the specified friend. The label of a friend is a private alias name for current user. It can be seen by current user only, and has no impact to the target friend itself.

Parameters:

userId - The friend's user identifier

label - The new label of specified friend

Throws:

java.lang.IllegalArgumentException - illegal exception.

CarrierException - carrier exception.

isFriend

public boolean isFriend(java.lang.String userId)
                 throws CarrierException

Check if the user ID is friend.

Parameters:

userId - The userId to check

Returns:

True if the user is a friend, or false if not

Throws:

java.lang.IllegalArgumentException - illegal exception.

CarrierException - carrier exception.

addFriend

public void addFriend(java.lang.String address,
                      java.lang.String hello)
               throws CarrierException

Add friend by sending a new friend request. This function will add a new friend with specific address, and then send a friend request to the target node.

Parameters:

address - the target user address of remote carrier node.

hello - PIN for target user, or any application defined content

Throws:

java.lang.IllegalArgumentException - illegal exception.

CarrierException - carrier exception.

acceptFriend

public void acceptFriend(java.lang.String userId)
                  throws CarrierException

Accept the friend request. This function is used to add a friend in response to a friend request.

Parameters:

userId - The user id who want be friend with us.

Throws:

java.lang.IllegalArgumentException - illegal exception.

CarrierException - carrier exception.

removeFriend

public void removeFriend(java.lang.String userId)
                  throws CarrierException

Remove a friend. This function will remove a friend on this carrier node.

Parameters:

userId - The target user id to remove friendship

Throws:

java.lang.IllegalArgumentException - illegal exception.

CarrierException - carrier exception.

sendFriendMessage

public long sendFriendMessage(java.lang.String to,
                              java.lang.String message,
                              FriendMessageReceiptHandler handler)
                       throws CarrierException

Send a message to a friend. The message length may not exceed CARRIER_MAX_USER_NAME_LEN, and message itself should be text-formatted. Larger messages must be split by application and sent as separate messages. Other nodes can reassemble the fragments.

Parameters:

to - The target id

message - The message content defined by application

handler - The handler to receive the receipt notification.

Returns:

Return the message identifier which would be used for handler to invoke receipt notification.

Throws:

java.lang.IllegalArgumentException - illegal exception.

CarrierException - carrier exception.

sendFriendMessage

public long sendFriendMessage(java.lang.String to,
                              byte[] message,
                              FriendMessageReceiptHandler handler)
                       throws CarrierException

Send a message to a friend. The message length may not exceed CARRIER_MAX_USER_NAME_LEN, and message itself should be text-formatted. Larger messages must be split by application and sent as separate messages. Other nodes can reassemble the fragments.

Parameters:

to - The target id

message - The message content defined by application

handler - The handler to receive the receipt notification.

Returns:

Return the message identifier which would be used for handler to invoke receipt notification.

Throws:

java.lang.IllegalArgumentException - illegal exception.

CarrierException - carrier exception.

inviteFriend

public void inviteFriend(java.lang.String to,
                         java.lang.String data,
                         FriendInviteResponseHandler handler)
                  throws CarrierException

Send invite request to a friend. Application can attach the application defined data with in the invite request, and the data will send to target friend.

Parameters:

to - The target id

data - The application defined data send to target user

handler - The handler to receive invite reponse

Throws:

java.lang.IllegalArgumentException - illegal exception.

CarrierException - carrier exception.

replyFriendInvite

public void replyFriendInvite(java.lang.String to,
                              int status,
                              java.lang.String reason,
                              java.lang.String data)
                       throws CarrierException

Reply the friend invite request. This function will send a invite response to friend.

Parameters:

to - The id who send invite request

status - The status code of the response. 0 is success, otherwise is error

reason - The error message if status is error, or null if success

data - The application defined data send to target user. If the status is error, this will be ignored

Throws:

java.lang.IllegalArgumentException - illegal exception.

CarrierException - carrier exception.

newGroup

public Group newGroup()
               throws CarrierException

Create a new group.

Returns:

The instance of the newly created group

Throws:

CarrierException - carrier exception.

groupJoin

public Group groupJoin(java.lang.String friendId,
                       byte[] cookie)
                throws CarrierException

Join a group associating with cookie into which remote friend invites. This function should be called only if application received a group invitation from remote friend.

Parameters:

friendId - The friend who send a group invitation

cookie - The cookie information to join group

Returns:

The instance of the group joined in

Throws:

java.lang.IllegalArgumentException - illegal exception.

CarrierException - carrier exception.

groupLeave

public void groupLeave(Group group)
                throws CarrierException

Leave a group.

Parameters:

group - The instance of the group to leave

Throws:

java.lang.IllegalArgumentException - illegal exception.

CarrierException - carrier exception.

getGroups

public java.util.Collection<Group> getGroups()

Get groups in the Carrier instance.

Returns:

A collection of groups joined in