ServiceLocator is the primary entry point into HDR and helps create HDR sessions. Although ServiceLocator is used in the same way for remote or local access to HDR, its usage varies depending on whether it is used inside or outside of a container. Use it for the following functions:
Establishing HDR sessions
Configuring the access mode (local or remote)
Retrieving handles to services through JNDI (Java Naming and Directory Interface)
Each ServiceLocator is associated with a single HDR session. Each HDR session defines an application-level context in which processing occurs. Services retrieved through a particular ServiceLocator instance receive that ServiceLocator session as their own. A ServiceLocator is used to establish a new HDR session.
ServiceLocator is configured by properties passed to the getInstance factory method. Three types of properties can be configured: JNDI properties, client mode, and authentication properties. The following table lists typical configuration parameters and their possible values. JNDI parameter values are used with an Oracle Application Service JNDI client library:
Service Locator Configuration Properties
| Property Name | Description | Values |
| javax.naming.Context.INITIAL_CONTEXT_FACTORY | Specifies the factory class used to instantiate context factory that is required by JNDI to establish initial connection. | For remote mode: "weblogic.jndi.WLInitialContextFactory"; not required in local mode. |
| javax.naming.Context.PROVIDER_URL | Specifies the location of the JNDI context containing HDR bean bindings. | For remote mode: "t3://hostname:port" where "hostname" is the host running HDR and port is the WebLogic admin port configured for the Application Service; not required in local mode. |
| javax.naming.Context.SECURITY_PRINCIPAL | Specifies the JNDI principal; is set by ServiceLocator.login when a session is created. | When creating a ServiceLocator for an existing session, the value must be identical to the username passed to ServiceLocator.login when the session was established. |
| javax.naming.Context.SECURITY_CREDENTIALS | Specifies the JNDI credential; is set by ServiceLocator.login when a session is created. | When creating a ServiceLocator for an existing session, the value must be identical to the password passed to ServiceLocator.login when the session was established. |
| ServiceLocator.CLIENT_MODE | Specifies whether the ServiceLocator should attempt to connect to Remote or Locale EJBs | ServiceLocator.REMOTE or ServiceLocator.LOCAL. The default is ServiceLocator.REMOTE. |
JNDI properties (named in table, with names starting with javax.naming.Context) can be configured by Java System properties, a jndi.properties file in the classpath, or by setting the values programmatically on the Properties passed to ServiceLocator.getInstance. The order of precedence is that programmatic properties override jndi file properties that in turn override Java System properties. We recommend that you always configure javax.naming.Context.INTIAL_CONTEXT_FACTORY and javax.naming.Context.PROVIDER_URL using Java System properties or jndi.properties to avoid unexpected behavior, and the need for extra configuration in your application code. You should configure the remaining configuration options on the Properties object that you pass to ServiceLocator.getInstance.
Note:
Always configure javax.naming.Context.INTIAL_CONTEXT_FACTORY and javax.naming.Context.PROVIDER_URL implicitly using jndi.properties or other Java System properties. Please refer to your Application Service documentation for more information.Example 4-1 illustrates typical usage of the ServiceLocator. The ServiceLocator is configured by creating a Properties class and configuring the JNDI and HDR client mode properties. The application then calls the login method that establishes a session between client and server. The application retrieves a service from the service locator by calling getRimService(), and calls logout to delete the session. Once logout has been called, the session is terminated and any services retrieved within that session cease to function.
This mode specifies which kind of EJB the ServiceLocator should attempt to retrieve from JNDI. In local mode, the ServiceLocator attempts to retrieve EJB local home interfaces and beans. In remote mode, the ServiceLocator attempts to retrieve EJB remote home interfaces and Beans. The two supported modes are defined the constants LOCAL and REMOTE on the ServiceLocator class. REMOTE is used by default if no other mode is specified. Each instance of ServiceLocator can function in only one mode.
Example 4-2 Setting the Client Mode
// Configure an Instance of ServiceLocator // Configure an Instance of ServiceLocator Properties properties = new Properties(); properties.setProperty(ServiceLocator.CLIENT_MODE, ServiceLocator.LOCAL); ServiceLocator serviceLocator = ServiceLocator.getInstance(properties); serviceLocator.login(username, password); // Retrieve a service RimService rimService = serviceLocator.getRimService();
This section describes the different behaviors of the ServiceLocator.login method in local and remote mode, and the effect of the Java Authentication and Authorization Service (JAAS) on HDR authentication.
The behavior of ServiceLocator.login depends on whether or not the calling code is protected by the application server:
If ServiceLocator.login is called from code running outside of a container, the identity and credentials passed to login are presented as the user name and password for the user when authenticating.
If ServiceLocator.login is called from code running outside of a container, the identity and credentials passed to login are presented as the user name and password for the user when authenticating.
If ServiceLocator.login is called from code running inside of a container (always the case in local mode), the behavior depends upon whether or not the application server has been configured to manage access to the component. If the component is protected by the container, the user name and password values are ignored; the ServiceLocator uses the user name and password of the current EJB session context (javax.ejb.SessionContext), which is established by the application server before it permits access to the component. The behavior for unprotected components is more complicated and is described below.
Note:
ServiceLocator.login ignores the user name and password passed to it when executing within a protected component within an application server, and uses the user name associated with the current EJB SessionContext. That user has to be authorized to access HDR functionality by both JAAS and the HDR Security Service. Session initiation otherwise fails and a Session could not be created authorization exception is thrown.When calling ServiceLocator.login from code running inside of a container, the ServiceLocator.login call only succeeds if made from within a component whose EJB SessionContext includes details of an authenticated user. Users are associated with an EJB SessionContext when they first attempt access to a protected component. The deployment configuration of your application and WebLogic determine which components are protected. If a component is protected, the application server authenticates any user before permitting access to the component. For web applications, this is typically achieved through a login screen.
Once authenticated, the user identity can be propagated between components. This essentially means that a call to ServiceLocator.login may fail if it is called from an unprotected component and no authentication has occurred. You should thus ensure that you protect the entry points to your applications with an appropriate security constraint in your WebLogic deployment descriptors.
Example 4-3 Use ServiceLocator by Calling Login From a Remote Client
This code sample uses ServiceLocator by calling Login from an RMI Client outside of an WebLogic:
Properties properties = new Properties();
properties.setProperty(ServiceLocator.CLIENT_MODE, ServiceLocator.REMOTE);
ServiceLocator serviceLocator = ServiceLocator.getInstance(properties);
serviceLocator.login("userName", "password");
RimService rimService = serviceLocator.getRimService();
IMPService impService = serviceLocator.getIMPService();
serviceLocator.logout();
Note that services are not usable after ServiceLocator.logout().
Before accessing HDR Services you must connect to and authenticate with HDR. The authentication process is carried out through JAAS by the WebLogic, the underlying application server. JAAS in turn delegates these requests to a provider that authenticates users against a repository, and determines authorization based on EJB deployment descriptors and other application server configuration files. JAAS also provides access authorization to particular EJBs and EJB methods.
The following key fundamentals relate to the behavior and use of the ServiceLocator:
JAAS authentication is a function of establishing a session with the application server. If authentication is successful, the authenticated user details are used to authenticate with JAAS when attempting to access protected EJB components.
JAAS authorization occurs whenever a user attempts access to a protected resource (for example, an HDR Service EJB). JAAS authorization is in addition to that provided by HDR Authorization mechanisms.
JAAS is configured with a separate repository of user names as passwords (such as an LDAP server), outside of HDR. External user repositories such as Oracle Identity Management Suite can be integrated with WebLogic server.
See Also:
The WebLogic application server documentation. For more information about available JAAS providers, JAAS configuration, and use by WebLogic, follow this link:https://docs.oracle.com/middleware/12213/wls/SCPRG/fat_client.htm#SCPRG224.