NotesFactory (Java™)

Applications call the NotesFactory createSession methods to create a Session object.

Local calls based on Notes® ID

For applications making local calls based on the Notes® user ID, create a Session object as follows. A Domino® server or Notes® client must be installed locally.

createSession() - No password verification occurs; the user is prompted for a password if the notes.id file is not open.
createSession((String)null, (String)null, (String)null) - Same as the preceding.
createSession((String)null, (String)null, passwordString) - Access is granted if the password matches the Notes® user ID password.
createTrustedSession() - No password verification occurs; the user is prompted for a password if the notes.id file is not open. If this method is called from an agent, an error will be thrown. See as follows for more information.

Note: The createTrustedSession method is new with Release 8.0.1.

On servers, the preceding methods restrict access according to Readers fields. For full access use the following methods. These methods also work but are unnecessary on clients.

createSessionWithFullAccess() - No password verification occurs; the user is prompted for a password if the notes.id file is not open.
createSessionWithFullAccess(passwordString) - Access is granted if the password matches the Notes® user ID password.
Note: The createSessionWithFullAccess methods are new with Release 6.

Trusted sessions

The following local call provides unrestricted access to a server:

createTrustedSession() - No password verification occurs; the user is prompted for a password if the notes.id file is not open. If this method is called from an agent, an error will be thrown. See as follows for more information.

Note: The createTrustedSession method is new with Release 8.0.1.

This method is a special purpose Java-only constructor intended for use by a very narrow class of server-resident applications.

The trusted session has special abilities and places a heavy responsibility on the application. A trusted session can access any database on the server. The application developer has full responsibility for providing security. Great care must be taken to avoid security issues.

Trusted sessions are not available to any code package that can replicate to a server. Therefore this method is not supported for agents or XPages. To obtain a trusted session, the application must be physically installed on the server hardware, for example, as a servlet, add-in, or freestanding application.

An example of an application that would use trusted sessions is a data reflection application server, which monitors changes to a group of mail files and reflects the modifications to another destination, such as a mobile device.

Local calls based on Domino® Directory

For applications making local calls based on the Domino® Directory, create an Internet Session object as follows. A Domino® Server must be installed locally.

createSession((String)null, "", "") - Anonymous Internet access is granted to the session if the server's Server record in the local Domino® Directory permits anonymous access. Parameter two must be an empty string, not null.
createSession((String)null, userString, passwordString) - Internet access is granted to the session if the password matches the Internet password in the user's Person record in the Domino® Directory.

Remote calls based on Domino® Directory

For applications making remote (IIOP) calls based on the host server's Domino® Directory, create an Internet Session object as follows, where hostString is the host name or IP address of the Domino® server (not the Domino® server name). The specification of a host name or IP address determines the use of the remote interface. A host name can be suffixed with the port number that the HTTP or DIIOP task uses to listen for TCP (non-SSL) connections using the syntax hostname:port (hostname-colon-port).

Note: The ability to specify a port number is new with Release 6.

createSession(hostString, "", "") - Anonymous Internet access is granted to the session if the host's Server record in the host's Domino® Directory permits anonymous access. Parameter two must be an empty string, not null.
createSession(hostString, userString, passwordString) - Internet access is granted to the session if the password matches the Internet password in the user's Person record in the host's Domino® Directory.

Internet Sessions further restrict access according to the "Server Access" and "Programmability Restrictions" sections of the applicable Server record, and the "Maximum Internet name & password" section of the target database's ACL (Advanced tab).

Single sign-on

To access a server using single sign-on, create an Internet Session object as follows. For remote (IIOP) calls, the first parameter is the host name or IP address of the Domino® server. For local calls, the first parameter is null.

createSession(hostString, tokenString) - Internet access is granted to the session based on the token. The token must be a valid token for single sign-on obtained from Session.getSessionToken, the LtpaToken cookie used by WebSphere®, or the HTTP cookie list in a servlet.
createSession(hostString, Credentials) - Internet access is granted to the session based on an org.omg.SecurityLevel2.Credentials object. This method works in a WebSphere® environment where the Credentials object is created using loginHelper.
createSession(hostString, (String)null) - Internet access is granted to the session based on the current Credentials object in the WebSphere® environment. This method works from an Enterprise JavaBeans™ (EJB) application in WebSphere®.
createSession(hostString, HttpServletRequest) - Internet access is granted to the session based on authentication by the Domino® HTTP server.

Note: Single Sign-on is new with Release 5.0.5.

To enable SSL (Secure Sockets Layer), use the String args[] parameter and specify "-ORBEnableSSLSecurity" as an element of the args array. For remote (IIOP) applications, the client must have access to the server's trusted root certificate, stored in TrustedCerts.class in domino/java in the server's data directory. This file is generated by the DIIOP task when it starts and is enabled to listen on the SSL port specified in the server document. The HTTP task delivers TrustedCerts.class to applets. For other applications, ensure that TrustedCerts.class is on the classpath.

Explicit IOR

The methods named createSessionWithIOR get an Internet session through explicit specification of the IOR. Typically this is not necessary. The createSession methods that specify a host call getIOR, which gets the IOR by querying the HTTP or DIIOP task listening on hostname:port for a file named diiop_ior.txt. Use the createSessionWithIOR methods if you have another mechanism for getting the IOR.

If only the HTTPS port can deliver the IOR, call getIOR with the String args[] parameter and specify -HTTPEnableSSLSecurity as an element of the args[] array. Then use the returned IOR in a createSessionWithIOR call.

If a file other than TrustedCerts.class contains the server's trusted root certificate, specify -ORBSSLCertificates=filenameas an element of the args[] array. The DIIOP task generates TrustedCerts.class and a duplicate file if DIIOP_DUP_KEYRING=filename is present as a notes.ini variable. This is useful to access two servers with different trusted root certificates.

A getIOR operation is not authenticated even with SSL.

Use a getIOR method with user and passwd parameters if anonymous access is not allowed on the HTTP or HTTPS port being accessed.

Note: The getIOR methods that take args[], user, and passwd parameters are new with Release 6.5.

Existing ORB

The createSession methods that include an org.omg.CORBA.ORB parameter create a session using an existing ORB, which you first create with one of the createORB methods. Using one ORB for multiple sessions (connection pooling) saves network overhead. However, make sure the connection can handle all the sessions you create, and be sure to recycle when you terminate a session.

Applets and agents

For applets, use AppletBase.openSession. For agents, use AgentBase.getSession.

Specification of NotesFactory

The specification of the NotesFactory class is as follows:

public class NotesFactory {
    /* Local session - Notes client must be installed */
    static public Session createSessionWithFullAccess()
        throws NotesException
    static public Session createSessionWithFullAccess(String passwd)
        throws NotesException
    static public Session createSession()
        throws NotesException
    /* Remote (IIOP) session using host name */
    static public Session createSession(String host)
        throws NotesException
    static public Session createSession(String host,
        String user, String passwd)
        throws NotesException
    static public Session createSession(String host,
        String args[], String user, String passwd)
        throws NotesException
    static public Session createSession(String host,
        org.omg.CORBA.ORB orb, String user, String passwd)
        throws NotesException
    /* Remote (IIOP) session using IOR */
    static public Session createSessionWithIOR(String IOR)
        throws NotesException
    static public Session createSessionWithIOR(String IOR,
        String user, String passwd)
        throws NotesException
    static public Session createSessionWithIOR(String IOR,
        String args[], String user, String passwd)
        throws NotesException
    static public Session createSessionWithIOR(String IOR,
        org.omg.CORBA.ORB orb, String user, String passwd)
        throws NotesException
    /* Remote (IIOP) session for applet */
    static public Session createSession(java.applet.Applet app,
        String user, String passwd)
        throws NotesException
    static public Session createSession(java.applet.Applet app,
        org.omg.CORBA.ORB orb, String user, String passwd)
        throws NotesException
    /* For Single Sign-on */
    static public Session createSession(String host,
        String cookie)
        throws NotesException
    static public Session createSession(String host,
        org.omg.SecurityLevel2.Credentials token)
        throws NotesException
    static public Session createSession(String host,
        HttpServletRequest request)
    static public Session createSession(String host,
        String args[], String cookie)
        throws NotesException
    static public Session createSession(String host,
        String args[], org.omg.SecurityLevel2.Credentials token)
        throws NotesException
    static public Session createSession(String host,
        String args[], HttpServletRequest request)
        throws NotesException
    static public Session createSession(String host,
        org.omg.CORBA.Orb orb, String cookie)
        throws NotesException
    static public Session createSession(String host,
        org.omg.CORBA.Orb orb, org.omg.SecurityLevel2.Credentials token)
        throws NotesException
    static public Session createSession(String host,
        org.omg.CORBA.Orb orb, HttpServletRequest request)
        throws NotesException
    static public Session createSessionWithIOR(String IOR,
        String cookie)
        throws NotesException
    static public Session createSessionWithIOR(String IOR,
        org.omg.SecurityLevel2.Credentials token)
        throws NotesException
    static public Session createSessionWithIOR(String IOR,
        HttpServletRequest request)
    static public Session createSessionWithIOR(String IOR,
        String args[], String cookie)
        throws NotesException
    static public Session createSessionWithIOR(String IOR,
        String args[], org.omg.SecurityLevel2.Credentials token)
        throws NotesException
    static public Session createSessionWithIOR(String IOR,
        String args[], HttpServletRequest request)
        throws NotesException
    static public Session createSessionWithIOR(String IOR,
        org.omg.CORBA.Orb orb, String cookie)
        throws NotesException
    static public Session createSessionWithIOR(String IOR,
        org.omg.CORBA.Orb orb, org.omg.SecurityLevel2.Credentials token)
        throws NotesException
    static public Session createSessionWithIOR(String IOR,
        org.omg.CORBA.Orb orb, HttpServletRequest request)
        throws NotesException
    /* Login to Websphere with session using LPTA token */
    static public Object getCredentials(Session sess)
        throws NotesException
    /* Create an ORB for connection sharing */
    static public org.omg.CORBA.ORB createORB()
    static public org.omg.CORBA.ORB createORB(String args[])
    static public org.omg.CORBA.ORB createORB(Properties props)
    /* Get IOR from host */
    static public String getIOR(String host)
        throws NotesException;
    static public String getIOR(String host,
        String user, String passwd)
        throws NotesException;
    static public String getIOR(String host, String args[])
        throws NotesException;
    static public String getIOR(String host, String args[],
        String user, String passwd)
        throws NotesException;
}

Example