net.java.sip.communicator.service.protocol
Class ProtocolProviderFactory

java.lang.Object
  net.java.sip.communicator.service.protocol.ProtocolProviderFactory

Direct Known Subclasses:

ProtocolProviderFactoryDictImpl, ProtocolProviderFactoryGibberishImpl, ProtocolProviderFactoryIcqImpl, ProtocolProviderFactoryIrcImpl, ProtocolProviderFactoryJabberImpl, ProtocolProviderFactoryMsnImpl, ProtocolProviderFactoryRssImpl, ProtocolProviderFactorySipImpl, ProtocolProviderFactorySSH, ProtocolProviderFactoryYahooImpl, ProtocolProviderFactoryZeroconfImpl

public abstract class ProtocolProviderFactory
extends Object

The ProtocolProviderFactory is what actually creates instances of a ProtocolProviderService implementation. A provider factory would register, persistently store, and remove when necessary, ProtocolProviders. The way things are in the SIP Communicator, a user account is represented (in a 1:1 relationship) by an AccountID and a ProtocolProvider. In other words - one would have as many protocol providers installed in a given moment as they would user account registered through the various services.

Author:

Emil Ivov, Lubomir Marinov

Field Summary

static String	ACCOUNT_DISPLAY_NAME The name that should be displayed to the user on call via and chat via lists.
static String	ACCOUNT_ICON_PATH The name of a property representing the path to the account icon to be used in the user interface, when the protocol provider service is not available.
static String	ACCOUNT_UID The name of the property under which we store protocol AccountID-s.
static String	AUTHORIZATION_NAME The name of the property under which we store the the authorization name for the proxy stored against the PROXY_ADDRESS property.
static String	AUTO_CHANGE_USER_NAME The name of the property under which we store the boolean value indicating if the user name should be automatically changed if the specified name already exists.
static String	AUTO_DISCOVER_JINGLE_NODES Indicates if JingleNodes should be used with ICE.
static String	AUTO_DISCOVER_STUN Indicates if STUN server should be automatically discovered.
static String	AUTO_GENERATE_RESOURCE The name of the property under which we store whether we generate resource values or we just use the stored one.
static String	CLIENT_TLS_CERTIFICATE The name of the property which defines the ID of the client TLS certificate configuration entry.
static String	DEFAULT_ENCRYPTION The name of the property which defines that the call is encrypted by default
static String	DEFAULT_SIPZRTP_ATTRIBUTE The name of the property which defines if to include the ZRTP attribute to SIP/SDP
static String	DISPLAY_NAME The name that should be displayed to others when we are calling or writing them.
static String	FORCE_P2P_MODE The name of the property under which we store if the p2p mode for SIMPLE should be forced.
static String	FORCE_PROXY_BYPASS The name of the property that indicates whether loose routing should be forced for all traffic in an account, rather than routing through an outbound proxy which is the default for Jitsi.
static String	IS_ACCOUNT_DISABLED The name of the property that would indicate if a given account is currently enabled or disabled.
static String	IS_ALLOW_NON_SECURE Indicates if we allow non-TLS connection.
static String	IS_CALLING_DISABLED_FOR_ACCOUNT Indicates if calling is disabled for a certain account.
static String	IS_DESKTOP_STREAMING_DISABLED Indicates if desktop streaming/sharing is disabled for a certain account.
static String	IS_PREFERRED_PROTOCOL Indicates if the given account is the preferred account.
static String	IS_PRESENCE_ENABLED The name of the property under which we store if the presence is enabled.
static String	IS_PROTOCOL_HIDDEN Indicates a protocol that would not be shown in the user interface as an account.
static String	IS_SERVER_OVERRIDDEN Indicates if the server settings are over
static String	IS_USE_GOOGLE_ICE Indicates if Google ICE should be used.
static String	IS_USE_ICE Indicates if ICE should be used.
static String	IS_USE_JINGLE_NODES Indicates if JingleNodes should be used with ICE.
static String	IS_USE_UPNP Indicates if UPnP should be used with ICE.
static String	KEEP_ALIVE_INTERVAL The interval for keep-alives if any.
static String	KEEP_ALIVE_METHOD Keep-alive method used by the protocol.
static String	NO_PASSWORD_REQUIRED The name of the property under which we store the boolean value indicating if a password is required.
static String	PASSWORD Then name of a property which represents a password.
static String	POLLING_PERIOD The name of the property under which we store the offline contact polling period for SIMPLE.
static String	PREFERRED_CLEAR_PORT_PROPERTY_NAME The property indicating the preferred UDP and TCP port to bind to for clear communications.
static String	PREFERRED_SECURE_PORT_PROPERTY_NAME The property indicating the preferred TLS (TCP) port to bind to for secure communications.
static String	PREFERRED_TRANSPORT The name of the property under which we store the user preference for a transport protocol to use (i.e.
static String	PROTOCOL The name of a property representing the name of the protocol for an ProtocolProviderFactory.
static String	PROTOCOL_ICON_PATH The name of a property representing the path to protocol icons.
static String	PROXY_ADDRESS The name of the property under which we store protocol the address of a protocol proxy.
static String	PROXY_ADDRESS_VALIDATED Indicates if the proxy address has been validated.
static String	PROXY_AUTO_CONFIG The name of the property which defines whether proxy is auto configured by the protocol by using known methods such as specific DNS queries.
static String	PROXY_PASSWORD The name of the property under which we store the password for the proxy stored against the PROXY_ADDRESS property.
static String	PROXY_PORT The name of the property under which we store the number of the port where the proxy stored against the PROXY_ADDRESS property is expecting connections to be made via this protocol.
static String	PROXY_TRANSPORT The name of the property under which we store the name of the transport protocol that needs to be used to access the proxy.
static String	PROXY_TYPE The name of the property under which we store the the type of the proxy stored against the PROXY_ADDRESS property.
static String	PROXY_USERNAME The name of the property under which we store the the username for the proxy stored against the PROXY_ADDRESS property.
protected Hashtable<AccountID,org.osgi.framework.ServiceRegistration>	registeredAccounts The table that we store our accounts in.
static String	RESOURCE The name of the property under which we store resources such as the jabber resource property.
static String	RESOURCE_PRIORITY The name of the property under which we store resource priority.
static int	SAVP_MANDATORY Always use RTP/SAVP
static int	SAVP_OFF Always use RTP/AVP
static String	SAVP_OPTION The name of the property that indicates the AVP type.
static int	SAVP_OPTIONAL Sends two media description, with RTP/SAVP being first.
static String	SDES_CIPHER_SUITES The name of the property that defines the enabled SDES cipher suites.
static String	SDES_ENABLED The name of the property that indicates if SDES is enabled for this account.
static String	SERVER_ADDRESS The name of the property under which we store protocol the address of a protocol centric entity (any protocol server).
static String	SERVER_ADDRESS_VALIDATED Indicates if the server address has been validated.
static String	SERVER_PORT The name of the property under which we store the number of the port where the server stored against the SERVER_ADDRESS property is expecting connections to be made via this protocol.
static String	SERVER_TRANSPORT The name of the property under which we store the name of the transport protocol that needs to be used to access the server.
static String	SMS_SERVER_ADDRESS The sms default server address.
static String	STRATEGY Indicates the search strategy chosen for the DICT protocole.
static String	STUN_ADDRESS The base property name for address of additional STUN servers specified.
static String	STUN_IS_TURN_SUPPORTED The base property name for the turn supported property of additional STUN servers specified.
static String	STUN_PASSWORD The base property name for password of additional STUN servers specified.
static String	STUN_PORT The base property name for port of additional STUN servers specified.
static String	STUN_PREFIX The property name prefix for all stun server properties.
static String	STUN_USERNAME The base property name for username of additional STUN servers specified.
static String	SUBSCRIPTION_EXPIRATION The name of the property under which we store the chosen default subscription expiration value for SIMPLE.
static String	USE_DEFAULT_STUN_SERVER Indicates if default STUN server would be used if no other STUN/TURN server are available.
static String	USER_ID The name of a property which represents the AccountID of a ProtocolProvider and that, together with a password is used to login on the protocol network..
static String	VOICEMAIL_URI Address used to reach voicemail box, by services able to subscribe for voicemail new messages notifications.

Constructor Summary

protected

ProtocolProviderFactory(org.osgi.framework.BundleContext bundleContext, String protocolName) Creates a new ProtocolProviderFactory.

Method Summary

AccountID	createAccount(Map<String,String> accountProperties) Initializes and creates an account corresponding to the specified accountProperties.
protected abstract AccountID	createAccountID(String userID, Map<String,String> accountProperties) Creates a new AccountID instance with a specific user ID to represent a given set of account properties.
protected abstract ProtocolProviderService	createService(String userID, AccountID accountID) Initializes a new ProtocolProviderService instance with a specific user ID to represent a specific AccountID.
static String	findAccountPrefix(org.osgi.framework.BundleContext bundleContext, AccountID accountID, String sourcePackageName) Returns the prefix for all persistently stored properties of the account with the specified id.
org.osgi.framework.BundleContext	getBundleContext() Gets the BundleContext containing (or to contain) the service registration of this factory.
String	getProtocolName() Gets the name of the protocol this factory registers its ProtocolProviderServices with and to be placed in the properties of the accounts created by this factory.
org.osgi.framework.ServiceReference	getProviderForAccount(AccountID accountID) Returns the ServiceReference for the protocol provider corresponding to the specified accountID or null if the accountID is unknown.
ArrayList<AccountID>	getRegisteredAccounts() Returns a copy of the list containing the AccountIDs of all accounts currently registered in this protocol provider.
abstract AccountID	installAccount(String userID, Map<String,String> accountProperties) Initializes and creates an account corresponding to the specified accountProperties and registers the resulting ProtocolProvider in the context BundleContext parameter.
boolean	loadAccount(AccountID accountID) Creates a protocol provider for the given accountID and registers it in the bundle context.
AccountID	loadAccount(Map<String,String> accountProperties) Initializes and creates an account corresponding to the specified accountProperties and registers the resulting ProtocolProvider in the context BundleContext parameter.
String	loadPassword(AccountID accountID) Returns the password last saved for the specified account.
protected String	loadPassword(org.osgi.framework.BundleContext bundleContext, AccountID accountID) Returns the password last saved for the specified account.
abstract void	modifyAccount(ProtocolProviderService protocolProvider, Map<String,String> accountProperties) Modifies the account corresponding to the specified accountID.
protected boolean	removeStoredAccount(AccountID accountID) Removes the account with accountID from the set of accounts that are persistently stored inside the configuration service.
void	stop() Prepares the factory for bundle shutdown.
protected void	stop(org.osgi.framework.ServiceRegistration registeredAccount) Shuts down the ProtocolProviderService representing an account registered with this factory.
protected void	storeAccount(AccountID accountID) The method stores the specified account in the configuration service under the package name of the source factory.
protected void	storeAccount(AccountID accountID, boolean isModification) The method stores the specified account in the configuration service under the package name of the source factory.
void	storePassword(AccountID accountID, String password) Saves the password for the specified account after scrambling it a bit so that it is not visible from first sight.
protected void	storePassword(org.osgi.framework.BundleContext bundleContext, AccountID accountID, String password) Saves the password for the specified account after scrambling it a bit so that it is not visible from first sight (Method remains highly insecure).
boolean	uninstallAccount(AccountID accountID) Removes the specified account from the list of accounts that this provider factory is handling.
boolean	unloadAccount(AccountID accountID) Unloads the account corresponding to the given accountID.

Methods inherited from class java.lang.Object

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

Field Detail

PASSWORD

public static final String PASSWORD

Then name of a property which represents a password.

See Also:

Constant Field Values

PROTOCOL

public static final String PROTOCOL

The name of a property representing the name of the protocol for an ProtocolProviderFactory.

See Also:

Constant Field Values

PROTOCOL_ICON_PATH

public static final String PROTOCOL_ICON_PATH

The name of a property representing the path to protocol icons.

See Also:

Constant Field Values

ACCOUNT_ICON_PATH

public static final String ACCOUNT_ICON_PATH

The name of a property representing the path to the account icon to be used in the user interface, when the protocol provider service is not available.

See Also:

Constant Field Values

USER_ID

public static final String USER_ID

The name of a property which represents the AccountID of a ProtocolProvider and that, together with a password is used to login on the protocol network..

See Also:

Constant Field Values

DISPLAY_NAME

public static final String DISPLAY_NAME

The name that should be displayed to others when we are calling or writing them.

See Also:

Constant Field Values

ACCOUNT_DISPLAY_NAME

public static final String ACCOUNT_DISPLAY_NAME

The name that should be displayed to the user on call via and chat via lists.

See Also:

Constant Field Values

ACCOUNT_UID

public static final String ACCOUNT_UID

The name of the property under which we store protocol AccountID-s.

See Also:

Constant Field Values

SERVER_ADDRESS

public static final String SERVER_ADDRESS

The name of the property under which we store protocol the address of a protocol centric entity (any protocol server).

See Also:

Constant Field Values

SERVER_PORT

public static final String SERVER_PORT

The name of the property under which we store the number of the port where the server stored against the SERVER_ADDRESS property is expecting connections to be made via this protocol.

See Also:

Constant Field Values

SERVER_TRANSPORT

public static final String SERVER_TRANSPORT

The name of the property under which we store the name of the transport protocol that needs to be used to access the server.

See Also:

Constant Field Values

PROXY_ADDRESS

public static final String PROXY_ADDRESS

The name of the property under which we store protocol the address of a protocol proxy.

See Also:

Constant Field Values

PROXY_PORT

public static final String PROXY_PORT

The name of the property under which we store the number of the port where the proxy stored against the PROXY_ADDRESS property is expecting connections to be made via this protocol.

See Also:

Constant Field Values

PROXY_AUTO_CONFIG

public static final String PROXY_AUTO_CONFIG

The name of the property which defines whether proxy is auto configured by the protocol by using known methods such as specific DNS queries.

See Also:

Constant Field Values

PREFERRED_CLEAR_PORT_PROPERTY_NAME

public static final String PREFERRED_CLEAR_PORT_PROPERTY_NAME

The property indicating the preferred UDP and TCP port to bind to for clear communications.

See Also:

Constant Field Values

PREFERRED_SECURE_PORT_PROPERTY_NAME

public static final String PREFERRED_SECURE_PORT_PROPERTY_NAME

The property indicating the preferred TLS (TCP) port to bind to for secure communications.

See Also:

Constant Field Values

PROXY_TYPE

public static final String PROXY_TYPE

The name of the property under which we store the the type of the proxy stored against the PROXY_ADDRESS property. Exact type values depend on protocols and among them are socks4, socks5, http and possibly others.

See Also:

Constant Field Values

PROXY_USERNAME

public static final String PROXY_USERNAME

The name of the property under which we store the the username for the proxy stored against the PROXY_ADDRESS property.

See Also:

Constant Field Values

AUTHORIZATION_NAME

public static final String AUTHORIZATION_NAME

The name of the property under which we store the the authorization name for the proxy stored against the PROXY_ADDRESS property.

See Also:

Constant Field Values

PROXY_PASSWORD

public static final String PROXY_PASSWORD

The name of the property under which we store the password for the proxy stored against the PROXY_ADDRESS property.

See Also:

Constant Field Values

PROXY_TRANSPORT

public static final String PROXY_TRANSPORT

The name of the property under which we store the name of the transport protocol that needs to be used to access the proxy.

See Also:

Constant Field Values

FORCE_PROXY_BYPASS

public static final String FORCE_PROXY_BYPASS

The name of the property that indicates whether loose routing should be forced for all traffic in an account, rather than routing through an outbound proxy which is the default for Jitsi.

See Also:

Constant Field Values

PREFERRED_TRANSPORT

public static final String PREFERRED_TRANSPORT

The name of the property under which we store the user preference for a transport protocol to use (i.e. tcp or udp).

See Also:

Constant Field Values

AUTO_GENERATE_RESOURCE

public static final String AUTO_GENERATE_RESOURCE

The name of the property under which we store whether we generate resource values or we just use the stored one.

See Also:

Constant Field Values

RESOURCE

public static final String RESOURCE

The name of the property under which we store resources such as the jabber resource property.

See Also:

Constant Field Values

RESOURCE_PRIORITY

public static final String RESOURCE_PRIORITY

The name of the property under which we store resource priority.

See Also:

Constant Field Values

DEFAULT_ENCRYPTION

public static final String DEFAULT_ENCRYPTION

The name of the property which defines that the call is encrypted by default

See Also:

Constant Field Values

DEFAULT_SIPZRTP_ATTRIBUTE

public static final String DEFAULT_SIPZRTP_ATTRIBUTE

The name of the property which defines if to include the ZRTP attribute to SIP/SDP

See Also:

Constant Field Values

CLIENT_TLS_CERTIFICATE

public static final String CLIENT_TLS_CERTIFICATE

The name of the property which defines the ID of the client TLS certificate configuration entry.

See Also:

Constant Field Values

AUTO_CHANGE_USER_NAME

public static final String AUTO_CHANGE_USER_NAME

The name of the property under which we store the boolean value indicating if the user name should be automatically changed if the specified name already exists. This property is meant to be used by IRC implementations.

See Also:

Constant Field Values

NO_PASSWORD_REQUIRED

public static final String NO_PASSWORD_REQUIRED

The name of the property under which we store the boolean value indicating if a password is required. Initially this property is meant to be used by IRC implementations.

See Also:

Constant Field Values

IS_PRESENCE_ENABLED

public static final String IS_PRESENCE_ENABLED

The name of the property under which we store if the presence is enabled.

See Also:

Constant Field Values

FORCE_P2P_MODE

public static final String FORCE_P2P_MODE

The name of the property under which we store if the p2p mode for SIMPLE should be forced.

See Also:

Constant Field Values

POLLING_PERIOD

public static final String POLLING_PERIOD

The name of the property under which we store the offline contact polling period for SIMPLE.

See Also:

Constant Field Values

SUBSCRIPTION_EXPIRATION

public static final String SUBSCRIPTION_EXPIRATION

The name of the property under which we store the chosen default subscription expiration value for SIMPLE.

See Also:

Constant Field Values

SERVER_ADDRESS_VALIDATED

public static final String SERVER_ADDRESS_VALIDATED

Indicates if the server address has been validated.

See Also:

Constant Field Values

IS_SERVER_OVERRIDDEN

public static final String IS_SERVER_OVERRIDDEN

Indicates if the server settings are over

See Also:

Constant Field Values

PROXY_ADDRESS_VALIDATED

public static final String PROXY_ADDRESS_VALIDATED

Indicates if the proxy address has been validated.

See Also:

Constant Field Values

STRATEGY

public static final String STRATEGY

Indicates the search strategy chosen for the DICT protocole.

See Also:

Constant Field Values

IS_PROTOCOL_HIDDEN

public static final String IS_PROTOCOL_HIDDEN

Indicates a protocol that would not be shown in the user interface as an account.

See Also:

Constant Field Values

IS_PREFERRED_PROTOCOL

public static final String IS_PREFERRED_PROTOCOL

Indicates if the given account is the preferred account.

See Also:

Constant Field Values

IS_ACCOUNT_DISABLED

public static final String IS_ACCOUNT_DISABLED

The name of the property that would indicate if a given account is currently enabled or disabled.

See Also:

Constant Field Values

IS_USE_ICE

public static final String IS_USE_ICE

Indicates if ICE should be used.

See Also:

Constant Field Values

IS_USE_GOOGLE_ICE

public static final String IS_USE_GOOGLE_ICE

Indicates if Google ICE should be used.

See Also:

Constant Field Values

AUTO_DISCOVER_STUN

public static final String AUTO_DISCOVER_STUN

Indicates if STUN server should be automatically discovered.

See Also:

Constant Field Values

USE_DEFAULT_STUN_SERVER

public static final String USE_DEFAULT_STUN_SERVER

Indicates if default STUN server would be used if no other STUN/TURN server are available.

See Also:

Constant Field Values

STUN_PREFIX

public static final String STUN_PREFIX

The property name prefix for all stun server properties. We generally use this prefix in conjunction with an index which is how we store multiple servers.

See Also:

Constant Field Values

STUN_ADDRESS

public static final String STUN_ADDRESS

The base property name for address of additional STUN servers specified.

See Also:

Constant Field Values

STUN_PORT

public static final String STUN_PORT

The base property name for port of additional STUN servers specified.

See Also:

Constant Field Values

STUN_USERNAME

public static final String STUN_USERNAME

The base property name for username of additional STUN servers specified.

See Also:

Constant Field Values

STUN_PASSWORD

public static final String STUN_PASSWORD

The base property name for password of additional STUN servers specified.

See Also:

Constant Field Values

STUN_IS_TURN_SUPPORTED

public static final String STUN_IS_TURN_SUPPORTED

The base property name for the turn supported property of additional STUN servers specified.

See Also:

Constant Field Values

IS_USE_JINGLE_NODES

public static final String IS_USE_JINGLE_NODES

Indicates if JingleNodes should be used with ICE.

See Also:

Constant Field Values

AUTO_DISCOVER_JINGLE_NODES

public static final String AUTO_DISCOVER_JINGLE_NODES

Indicates if JingleNodes should be used with ICE.

See Also:

Constant Field Values

IS_USE_UPNP

public static final String IS_USE_UPNP

Indicates if UPnP should be used with ICE.

See Also:

Constant Field Values

IS_ALLOW_NON_SECURE

public static final String IS_ALLOW_NON_SECURE

Indicates if we allow non-TLS connection.

See Also:

Constant Field Values

VOICEMAIL_URI

public static final String VOICEMAIL_URI

Address used to reach voicemail box, by services able to subscribe for voicemail new messages notifications.

See Also:

Constant Field Values

IS_CALLING_DISABLED_FOR_ACCOUNT

public static final String IS_CALLING_DISABLED_FOR_ACCOUNT

Indicates if calling is disabled for a certain account.

See Also:

Constant Field Values

IS_DESKTOP_STREAMING_DISABLED

public static final String IS_DESKTOP_STREAMING_DISABLED

Indicates if desktop streaming/sharing is disabled for a certain account.

See Also:

Constant Field Values

SMS_SERVER_ADDRESS

public static final String SMS_SERVER_ADDRESS

The sms default server address.

See Also:

Constant Field Values

KEEP_ALIVE_METHOD

public static final String KEEP_ALIVE_METHOD

Keep-alive method used by the protocol.

See Also:

Constant Field Values

KEEP_ALIVE_INTERVAL

public static final String KEEP_ALIVE_INTERVAL

The interval for keep-alives if any.

See Also:

Constant Field Values

registeredAccounts

protected final Hashtable<AccountID,org.osgi.framework.ServiceRegistration> registeredAccounts

The table that we store our accounts in.

TODO Synchronize the access to the field which may in turn be better achieved by also hiding it from protected into private access.

SAVP_OPTION

public static final String SAVP_OPTION

The name of the property that indicates the AVP type.

• SAVP_OFF
• SAVP_MANDATORY
• SAVP_OPTIONAL

See Also:

Constant Field Values

SAVP_OFF

public static final int SAVP_OFF

Always use RTP/AVP

See Also:

Constant Field Values

SAVP_MANDATORY

public static final int SAVP_MANDATORY

Always use RTP/SAVP

See Also:

Constant Field Values

SAVP_OPTIONAL

public static final int SAVP_OPTIONAL

Sends two media description, with RTP/SAVP being first.

See Also:

Constant Field Values

SDES_CIPHER_SUITES

public static final String SDES_CIPHER_SUITES

The name of the property that defines the enabled SDES cipher suites. Enabled suites are listed as CSV by their RFC name.

See Also:

Constant Field Values

SDES_ENABLED

public static final String SDES_ENABLED

The name of the property that indicates if SDES is enabled for this account.

See Also:

Constant Field Values

Constructor Detail

ProtocolProviderFactory

protected ProtocolProviderFactory(org.osgi.framework.BundleContext bundleContext,
                                  String protocolName)

Creates a new ProtocolProviderFactory.

Parameters:

bundleContext - the bundle context reference of the service

protocolName - the name of the protocol

Method Detail

getBundleContext

public org.osgi.framework.BundleContext getBundleContext()

Gets the BundleContext containing (or to contain) the service registration of this factory.

Returns:

the BundleContext containing (or to contain) the service registration of this factory

installAccount

public abstract AccountID installAccount(String userID,
                                         Map<String,String> accountProperties)
                                  throws IllegalArgumentException,
                                         IllegalStateException,
                                         NullPointerException

Initializes and creates an account corresponding to the specified accountProperties and registers the resulting ProtocolProvider in the context BundleContext parameter. Note that account registration is persistent and accounts that are registered during a particular sip-communicator session would be automatically reloaded during all following sessions until they are removed through the removeAccount method.

Parameters:

userID - the user identifier uniquely representing the newly created account within the protocol namespace.

accountProperties - a set of protocol (or implementation) specific properties defining the new account.

Returns:

the AccountID of the newly created account.

Throws:

IllegalArgumentException - if userID does not correspond to an identifier in the context of the underlying protocol or if accountProperties does not contain a complete set of account installation properties.

IllegalStateException - if the account has already been installed.

NullPointerException - if any of the arguments is null.

modifyAccount

public abstract void modifyAccount(ProtocolProviderService protocolProvider,
                                   Map<String,String> accountProperties)
                            throws NullPointerException

Modifies the account corresponding to the specified accountID. This method is meant to be used to change properties of already existing accounts. Note that if the given accountID doesn't correspond to any registered account this method would do nothing.

Parameters:

protocolProvider - the protocol provider service corresponding to the modified account.

accountProperties - a set of protocol (or implementation) specific properties defining the new account.

Throws:

NullPointerException - if any of the arguments is null.

getRegisteredAccounts

public ArrayList<AccountID> getRegisteredAccounts()

Returns a copy of the list containing the AccountIDs of all accounts currently registered in this protocol provider.

Returns:

a copy of the list containing the AccountIDs of all accounts currently registered in this protocol provider.

getProviderForAccount

public org.osgi.framework.ServiceReference getProviderForAccount(AccountID accountID)

Returns the ServiceReference for the protocol provider corresponding to the specified accountID or null if the accountID is unknown.

Parameters:

accountID - the accountID of the protocol provider we'd like to get

Returns:

a ServiceReference object to the protocol provider with the specified account id and null if the account id is unknown to the provider factory.

uninstallAccount

public boolean uninstallAccount(AccountID accountID)

Removes the specified account from the list of accounts that this provider factory is handling. If the specified accountID is unknown to the ProtocolProviderFactory, the call has no effect and false is returned. This method is persistent in nature and once called the account corresponding to the specified ID will not be loaded during future runs of the project.

Parameters:

accountID - the ID of the account to remove.

Returns:

true if an account with the specified ID existed and was removed and false otherwise.

storeAccount

protected void storeAccount(AccountID accountID)

The method stores the specified account in the configuration service under the package name of the source factory. The restore and remove account methods are to be used to obtain access to and control the stored accounts.

In order to store all account properties, the method would create an entry in the configuration service corresponding (beginning with) the sourceFactory's package name and add to it a unique identifier (e.g. the current miliseconds.)

Parameters:

accountID - the AccountID corresponding to the account that we would like to store.

storeAccount

protected void storeAccount(AccountID accountID,
                            boolean isModification)

The method stores the specified account in the configuration service under the package name of the source factory. The restore and remove account methods are to be used to obtain access to and control the stored accounts.

In order to store all account properties, the method would create an entry in the configuration service corresponding (beginning with) the sourceFactory's package name and add to it a unique identifier (e.g. the current miliseconds.)

Parameters:

accountID - the AccountID corresponding to the account that we would like to store.

isModification - if false there must be no such already loaded account, it true ist modification of an existing account. Usually we use this method with false in method installAccount and with true or the overridden method in method modifyAccount.

storePassword

public void storePassword(AccountID accountID,
                          String password)
                   throws IllegalArgumentException

Saves the password for the specified account after scrambling it a bit so that it is not visible from first sight. (The method remains highly insecure).

Parameters:

accountID - the AccountID for the account whose password we're storing

password - the password itself

Throws:

IllegalArgumentException - if no account corresponding to accountID has been previously stored

storePassword

protected void storePassword(org.osgi.framework.BundleContext bundleContext,
                             AccountID accountID,
                             String password)
                      throws IllegalArgumentException,
                             OperationFailedException

Saves the password for the specified account after scrambling it a bit so that it is not visible from first sight (Method remains highly insecure).

TODO Delegate the implementation to AccountManager because it knows the format in which the password (among the other account properties) is to be saved.

Parameters:

bundleContext - a currently valid bundle context.

accountID - the AccountID of the account whose password is to be stored

password - the password to be stored

Throws:

IllegalArgumentException - if no account corresponding to accountID has been previously stored.

OperationFailedException - if anything goes wrong while storing the specified password

loadPassword

public String loadPassword(AccountID accountID)

Returns the password last saved for the specified account.

Parameters:

accountID - the AccountID for the account whose password we're looking for

Returns:

a String containing the password for the specified accountID

loadPassword

protected String loadPassword(org.osgi.framework.BundleContext bundleContext,
                              AccountID accountID)

Returns the password last saved for the specified account.

TODO Delegate the implementation to AccountManager because it knows the format in which the password (among the other account properties) was saved.

Parameters:

bundleContext - a currently valid bundle context.

accountID - the AccountID for the account whose password we're looking for..

Returns:

a String containing the password for the specified accountID.

loadAccount

public AccountID loadAccount(Map<String,String> accountProperties)

Initializes and creates an account corresponding to the specified accountProperties and registers the resulting ProtocolProvider in the context BundleContext parameter. This method has a persistent effect. Once created the resulting account will remain installed until removed through the uninstallAccount method.

Parameters:

accountProperties - a set of protocol (or implementation) specific properties defining the new account.

Returns:

the AccountID of the newly loaded account

loadAccount

public boolean loadAccount(AccountID accountID)

Creates a protocol provider for the given accountID and registers it in the bundle context. This method has a persistent effect. Once created the resulting account will remain installed until removed through the uninstallAccount method.

Parameters:

accountID - the account identifier

Returns:

true if the account with the given accountID is successfully loaded, otherwise returns false

unloadAccount

public boolean unloadAccount(AccountID accountID)

Unloads the account corresponding to the given accountID. Unregisters the corresponding protocol provider, but keeps the account in contrast to the uninstallAccount method.

Parameters:

accountID - the account identifier

Returns:

true if an account with the specified ID existed and was unloaded and false otherwise.

createAccount

public AccountID createAccount(Map<String,String> accountProperties)

Initializes and creates an account corresponding to the specified accountProperties.

Parameters:

accountProperties - a set of protocol (or implementation) specific properties defining the new account.

Returns:

the AccountID of the newly created account

createAccountID

protected abstract AccountID createAccountID(String userID,
                                             Map<String,String> accountProperties)

Creates a new AccountID instance with a specific user ID to represent a given set of account properties.

The method is a pure factory allowing implementers to specify the runtime type of the created AccountID and customize the instance. The returned AccountID will later be associated with a ProtocolProviderService by the caller (e.g. using createService(String, AccountID)).

Parameters:

userID - the user ID of the new instance

accountProperties - the set of properties to be represented by the new instance

Returns:

a new AccountID instance with the specified user ID representing the given set of account properties

getProtocolName

public String getProtocolName()

Gets the name of the protocol this factory registers its ProtocolProviderServices with and to be placed in the properties of the accounts created by this factory.

Returns:

the name of the protocol this factory registers its ProtocolProviderServices with and to be placed in the properties of the accounts created by this factory

createService

protected abstract ProtocolProviderService createService(String userID,
                                                         AccountID accountID)

Initializes a new ProtocolProviderService instance with a specific user ID to represent a specific AccountID.

The method is a pure factory allowing implementers to specify the runtime type of the created ProtocolProviderService and customize the instance. The caller will later register the returned service with the BundleContext of this factory.

Parameters:

userID - the user ID to initialize the new instance with

accountID - the AccountID to be represented by the new instance

Returns:

a new ProtocolProviderService instance with the specific user ID representing the specified AccountID

removeStoredAccount

protected boolean removeStoredAccount(AccountID accountID)

Removes the account with accountID from the set of accounts that are persistently stored inside the configuration service.

Parameters:

accountID - the AccountID of the account to remove.

Returns:

true if an account has been removed and false otherwise.

findAccountPrefix

public static String findAccountPrefix(org.osgi.framework.BundleContext bundleContext,
                                       AccountID accountID,
                                       String sourcePackageName)

Returns the prefix for all persistently stored properties of the account with the specified id.

Parameters:

bundleContext - a currently valid bundle context.

accountID - the AccountID of the account whose properties we're looking for.

sourcePackageName - a String containing the package name of the concrete factory class that extends us.

Returns:

a String indicating the ConfigurationService property name prefix under which all account properties are stored or null if no account corresponding to the specified id was found.

stop

public void stop()

Prepares the factory for bundle shutdown.

stop

protected void stop(org.osgi.framework.ServiceRegistration registeredAccount)

Shuts down the ProtocolProviderService representing an account registered with this factory.

Parameters:

registeredAccount - the ServiceRegistration of the ProtocolProviderService representing an account registered with this factory