de.bea.domingo
Class DNotesFactory

java.lang.Object
  extended by de.bea.domingo.DNotesFactory
Direct Known Subclasses:
NotesHttpFactory, NotesProxyFactory, NotesServiceFactory

public abstract class DNotesFactory
extends java.lang.Object

Main entry point for applications to the domingo-API.

Stand-alond client applications shall call the methos getInstance() method to obtain a singleton instance of the DSession interface. Domingo takes care of proper disposual of this singleton session instance.

Server based applications must call the newInstance(String) method to obtain a new instance of the

Once an application has obtained a reference to a DNotesFactory it can use the factory to obtain a Notes session.

Author:
Kurt Riede

Constructor Summary
protected DNotesFactory()
          Protected Constructor to restrict creation to sub classes.
 
Method Summary
static void dispose()
          Disposes the singleton instance of the factory.
static void dispose(boolean force)
          Disposes the singleton instance of the factory.
abstract  void disposeInstance()
          Disposes all internal resources of the Notes connection.
abstract  void disposeInstance(boolean force)
          Disposes all internal resources of the Notes connection.
abstract  void disposeInternal(boolean force)
          Deprecated. use disposeInstance(boolean) instead
protected abstract  void gc()
          Deprecated. only use this method for testing
static boolean getBooleanProperty(java.lang.String key, boolean defaultValue)
          Returns the integer value of a property or returns the given default value if no configuration found or if the value cannot be converted to an integer value.
static DNotesFactory getInstance()
          Returns a singleton instance of class DNotesFactory.
static DNotesFactory getInstance(DNotesMonitor theMonitor)
          Returns a singleton instance of class DNotesFactory.
static DNotesFactory getInstance(java.lang.String implementingClassName)
          Returns a singleton instance of class DNotesFactory.
static DNotesFactory getInstance(java.lang.String implementingClassName, DNotesMonitor theMonitor)
          Returns a singleton instance of class DNotesFactory.
static int getIntProperty(java.lang.String key, int defaultValue)
          Returns the integer value of a property or returns the given default value if no configuration found or if the value cannot be converted to an integer value.
protected abstract  DNotesMonitor getMonitor()
          Get the current monitor.
static java.lang.String getProperty(java.lang.String key, java.lang.String defaultValue)
          Returns the value of a property or returns the given default value if no configuration found.
abstract  DSession getSession()
          Creates a local session.
abstract  DSession getSession(java.applet.Applet applet, java.lang.String user, java.lang.String password)
          Creates a remote (IIOP) session for an applet.
abstract  DSession getSession(java.lang.Object notesSession)
          Creates a Domingo session for an existing Notes session.
abstract  DSession getSession(java.lang.String serverUrl)
          Creates a DIIOP session.
abstract  DSession getSession(java.lang.String serverUrl, java.lang.String[] args, java.lang.String user, java.lang.String password)
          Creates a remote (IIOP or Http) session with arguments using host name.
abstract  DSession getSession(java.lang.String serverUrl, java.lang.String user, java.lang.String password)
          Creates a remote (IIOP or Http) session using host name.
abstract  DSession getSessionSSL(java.lang.String serverUrl, java.lang.String user, java.lang.String password)
          Creates a remote (IIOP or Http) session with SSL using host name.
abstract  DSession getSessionWithFullAccess()
          Creates a local session.
abstract  DSession getSessionWithFullAccess(java.lang.String password)
          Creates a local session.
static DNotesFactory newInstance()
          Returns a new instance of class DNotesFactory.
static DNotesFactory newInstance(DNotesMonitor theMonitor)
          Returns a new instance of class DNotesFactory.
static DNotesFactory newInstance(java.lang.String implementingClassName)
          Returns a new instance of class DNotesFactory.
static DNotesFactory newInstance(java.lang.String implementingClassName, DNotesMonitor theMonitor)
          Returns a new instance of class DNotesFactory.
protected abstract  void setMonitor(DNotesMonitor theMonitor)
          Set the monitor.
static void setProperty(java.lang.String key, java.lang.String value)
          Sets a configuration value and overwrites any default or configuration settings.
abstract  void sinitThread()
          Enables Notes access for the current thread.
abstract  void stermThread()
          Disables Notes access for the current thread.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DNotesFactory

protected DNotesFactory()
Protected Constructor to restrict creation to sub classes.

Method Detail

getInstance

public static DNotesFactory getInstance()
                                 throws DNotesRuntimeException
Returns a singleton instance of class DNotesFactory.

This method uses the following ordered lookup procedure to determine the DNotesFactory implementation class to load:

Returns:
singleton instance of this factory
Throws:
DNotesRuntimeException - if the instance cannot be created

getInstance

public static DNotesFactory getInstance(java.lang.String implementingClassName)
                                 throws DNotesRuntimeException
Returns a singleton instance of class DNotesFactory.

Parameters:
implementingClassName - class name of implementation to use
Returns:
singleton instance of this factory
Throws:
DNotesRuntimeException - if the instance cannot be created

getInstance

public static DNotesFactory getInstance(java.lang.String implementingClassName,
                                        DNotesMonitor theMonitor)
                                 throws DNotesRuntimeException
Returns a singleton instance of class DNotesFactory.

Parameters:
implementingClassName - class name of implementation to use
theMonitor - the monitor
Returns:
singleton instance of this factory
Throws:
DNotesRuntimeException - if the instance cannot be created

getInstance

public static DNotesFactory getInstance(DNotesMonitor theMonitor)
                                 throws DNotesRuntimeException
Returns a singleton instance of class DNotesFactory.

This method uses the following ordered lookup procedure to determine the DNotesFactory implementation class to load:

Parameters:
theMonitor - the monitor
Returns:
singleton instance of this factory
Throws:
DNotesRuntimeException - if the instance cannot be created

newInstance

public static DNotesFactory newInstance()
                                 throws DNotesRuntimeException
Returns a new instance of class DNotesFactory.

It is up to the user to remember this instance and to keep it as a singleton if needed.

By default the implementing class is NotesProxyFactory.

Returns:
new instance of this factory
Throws:
DNotesRuntimeException - if the instance cannot be created
Since:
domingo 1.4

newInstance

public static DNotesFactory newInstance(DNotesMonitor theMonitor)
                                 throws DNotesRuntimeException
Returns a new instance of class DNotesFactory.

It is up to the user to remember this instance and to keep it as a singleton if needed.

By default the implementing class is NotesProxyFactory.

Parameters:
theMonitor - the monitor
Returns:
new instance of this factory
Throws:
DNotesRuntimeException - if the instance cannot be created
Since:
domingo 1.4

newInstance

public static DNotesFactory newInstance(java.lang.String implementingClassName,
                                        DNotesMonitor theMonitor)
                                 throws DNotesRuntimeException
Returns a new instance of class DNotesFactory.

It is up to the user to remember this instance and to keep it as a singleton if needed.

Parameters:
implementingClassName - class name of implementation to use
theMonitor - the monitor
Returns:
new instance of this factory
Throws:
DNotesRuntimeException - if the instance cannot be created
Since:
domingo 1.4

newInstance

public static DNotesFactory newInstance(java.lang.String implementingClassName)
                                 throws DNotesRuntimeException
Returns a new instance of class DNotesFactory.

It is up to the user to remember this instance and to keep it as a singleton if needed.

Parameters:
implementingClassName - class name of implementation to use
Returns:
new instance of this factory
Throws:
DNotesRuntimeException - if the instance cannot be created
Since:
domingo 1.4

getSession

public abstract DSession getSession()
                             throws DNotesRuntimeException
Creates a local session.

(Notes client must be installed)

Returns:
a local session
Throws:
DNotesRuntimeException - if the session cannot be created

getSession

public abstract DSession getSession(java.lang.String serverUrl)
                             throws DNotesRuntimeException
Creates a DIIOP session.

Parameters:
serverUrl - URL of server (e.g. "https://plato.acme:8080")
Returns:
a local session
Throws:
DNotesRuntimeException - if the session cannot be created

getSession

public abstract DSession getSession(java.lang.String serverUrl,
                                    java.lang.String user,
                                    java.lang.String password)
                             throws DNotesRuntimeException
Creates a remote (IIOP or Http) session using host name.

Parameters:
serverUrl - URL of server (e.g. "https://plato.acme:8080")
user - user name for authentication
password - password for for authentication
Returns:
a remote session
Throws:
DNotesRuntimeException - if the session cannot be created

getSessionSSL

public abstract DSession getSessionSSL(java.lang.String serverUrl,
                                       java.lang.String user,
                                       java.lang.String password)
                                throws DNotesRuntimeException
Creates a remote (IIOP or Http) session with SSL using host name.

Parameters:
serverUrl - URL of server (e.g. "https://plato.acme:8080")
user - user name for authentication
password - password for for authentication
Returns:
a remote session
Throws:
DNotesRuntimeException - if the session cannot be created

getSession

public abstract DSession getSession(java.lang.String serverUrl,
                                    java.lang.String[] args,
                                    java.lang.String user,
                                    java.lang.String password)
                             throws DNotesRuntimeException
Creates a remote (IIOP or Http) session with arguments using host name.

Parameters:
serverUrl - URL of server (e.g. "https://plato.acme:8080")
args - array of additional arguments
user - user name for authentication
password - password for for authentication
Returns:
a remote session
Throws:
DNotesRuntimeException - if the session cannot be created

getSession

public abstract DSession getSession(java.applet.Applet applet,
                                    java.lang.String user,
                                    java.lang.String password)
                             throws DNotesRuntimeException
Creates a remote (IIOP) session for an applet.

Parameters:
applet - applet instance
user - user name for authentication
password - password for for authentication
Returns:
a remote session for an applet
Throws:
DNotesRuntimeException - if the session cannot be created

getSession

public abstract DSession getSession(java.lang.Object notesSession)
                             throws DNotesRuntimeException
Creates a Domingo session for an existing Notes session.

This method is used only internally in Notes agents and Notes applets.

Parameters:
notesSession - existing Notes session
Returns:
a Domingo session for the given Notes session
Throws:
DNotesRuntimeException - if the session cannot be created

getSessionWithFullAccess

public abstract DSession getSessionWithFullAccess()
                                           throws DNotesRuntimeException
Creates a local session.

(Notes client must be installed)

Access restrictions according to readers items are bypassed.

Returns:
a local session
Throws:
DNotesRuntimeException - if the session cannot be created

getSessionWithFullAccess

public abstract DSession getSessionWithFullAccess(java.lang.String password)
                                           throws DNotesRuntimeException
Creates a local session.

(Notes client must be installed)

Access restrictions according to readers items are bypassed.

Parameters:
password - password for for authentication
Returns:
a local session
Throws:
DNotesRuntimeException - if the session cannot be created

getProperty

public static final java.lang.String getProperty(java.lang.String key,
                                                 java.lang.String defaultValue)
Returns the value of a property or returns the given default value if no configuration found.

Parameters:
key - the key of the property
defaultValue - default value, if no configuration found
Returns:
the value of the property

setProperty

public static void setProperty(java.lang.String key,
                               java.lang.String value)
Sets a configuration value and overwrites any default or configuration settings.

Parameters:
key - the key of the property
value - the new value

getIntProperty

public static final int getIntProperty(java.lang.String key,
                                       int defaultValue)
Returns the integer value of a property or returns the given default value if no configuration found or if the value cannot be converted to an integer value.

Parameters:
key - the key of the property
defaultValue - default value, if no configuration found
Returns:
the value of the property

getBooleanProperty

public static final boolean getBooleanProperty(java.lang.String key,
                                               boolean defaultValue)
Returns the integer value of a property or returns the given default value if no configuration found or if the value cannot be converted to an integer value.

Parameters:
key - the key of the property
defaultValue - default value, if no configuration found
Returns:
the value of the property

sinitThread

public abstract void sinitThread()
Enables Notes access for the current thread.


stermThread

public abstract void stermThread()
Disables Notes access for the current thread.


gc

protected abstract void gc()
Deprecated. only use this method for testing

Runs the garbage collector and tries to recycle all internal notes objects.

ATTENTION:

This method should not be used in productive code. It only exists for tests, e.g. to ensure clean memory before analyzing with JProbe.

See Also:
Runtime.gc()

dispose

public static void dispose()
                    throws DNotesRuntimeException
Disposes the singleton instance of the factory.

It is strictly recommended to call this method before exiting applications in order to not destabilize the Lotus Notes Client.

If a factory was created with a newInstance(String, DNotesMonitor) method, the factory must be disposed with the instance method disposeInstance(boolean).

Equivalent to {link disposeInstance(true)

.

Throws:
DNotesRuntimeException - if an error occurs during disposal or if not all objects can be disposed

dispose

public static void dispose(boolean force)
                    throws DNotesException
Disposes the singleton instance of the factory.

It is strictly recommended to call this method before exiting applications in order to not destabilize the Lotus Notes Client.

If a factory was created with a newInstance(String, DNotesMonitor) method, the factory must be disposed with the instance method disposeInstance(boolean).

Parameters:
force - indicates if disposal should happen even if still any string or soft reference exists. if false, only weak references must remain.
Throws:
DNotesException - if an error occurs during disposal or if not all objects can be disposed

disposeInternal

public abstract void disposeInternal(boolean force)
                              throws DNotesRuntimeException
Deprecated. use disposeInstance(boolean) instead

Disposes all internal resources of the Notes connection.

Parameters:
force - indicates if disposal should happen even if still any string or soft reference exists. if false, only weak references must remain.
Throws:
DNotesRuntimeException - if an error occurs during disposal or if not all objects can be disposed

disposeInstance

public abstract void disposeInstance(boolean force)
                              throws DNotesRuntimeException
Disposes all internal resources of the Notes connection.

Parameters:
force - indicates if disposal should happen even if still any string or soft reference exists. if false, only weak references must remain.
Throws:
DNotesRuntimeException - if an error occurs during disposal or if not all objects can be disposed

disposeInstance

public abstract void disposeInstance()
                              throws DNotesRuntimeException
Disposes all internal resources of the Notes connection.

Equivalent to {link disposeInstance(false)

.

Throws:
DNotesRuntimeException - if an error occurs during disposal or if not all objects can be disposed

getMonitor

protected abstract DNotesMonitor getMonitor()
Get the current monitor.

Returns:
current monitor

setMonitor

protected abstract void setMonitor(DNotesMonitor theMonitor)
Set the monitor.

Parameters:
theMonitor - the monitor


Domingo Java-API