Oracle® Fusion Middleware System Administrator's Guide for Oracle Business Intelligence Enterprise Edition 11g Release 1 (11.1.1) Part Number E10541-04 |
|
|
PDF · Mobi · ePub |
This chapter describes the Oracle BI Systems Management Application Programming Interface (API).
This chapter includes the following sections:
Section 22.1, "What Is the Oracle BI Systems Management API?"
Section 22.2, "Accessing Oracle BI Systems Management API Methods"
The Oracle BI Systems Management API is a programming interface that provides access to Oracle Business Intelligence JMX Admin MBeans, enabling a developer to programmatically perform system administration tasks for Oracle Business Intelligence. The system administration tasks that can be performed using the Oracle BI Systems Management API are also available using Fusion Middleware Control.
The Oracle BI Systems Management API centralizes the management of system configuration by automatically propagating changes to all of the files that require updates in multiple locations.
Alternative methods for modifying system configuration settings for Oracle Business Intelligence are available. For information, see Section 3.1, "Configuring Oracle Business Intelligence."
The Oracle BI Systems Management API and its Java methods are described in a JavaDoc file that is located in the following directory:
ORACLE_HOME/doc/javadoc/bifoundation/jmxapi/index.html
Note:
You cannot display the Log Viewer or Performance Metrics using the Oracle BI Systems Management API.
This section describes the following ways to access Oracle BI Systems Management API methods:
Using an Oracle WebLogic Server Scripting Tool (WLST) command (interactive mode)
You can use the command line to enter a command and view the response at a command-line prompt. This method is useful for learning the tool, prototyping command syntax, and verifying configuration options before building a script. Using WLST interactively is particularly useful for getting immediate feedback after making a critical configuration change. The WLST scripting shell maintains a persistent connection with an instance of WebLogic Server.
Using a WLST command in a script (Script mode)
You can use a script to invoke a sequence of WLST commands without requiring your input, much like a shell script. Scripts contain WLST commands in a text file with a .py file extension, such as filename.py. You use script files with the Jython commands for running scripts. The Jython scripting language is used because it is freely available and compatible with the Java platform.
Using a Java program
You can use a Java program to contact the JMX server directly.
For information about the Oracle BI Systems Management API methods, see Section 22.4, "Descriptions of JMX Admin MBeans and Methods for the Oracle BI Systems Management API."
This section describes using the Oracle BI Systems Management API to manage and configure Oracle Business Intelligence, and contains the following topics:
Section 22.3.3, "Updating Configuration Settings Using the Oracle BI Systems Management API"
Section 22.3.5, "Capturing Metrics Using the Oracle BI Systems Management API"
You can use the Oracle BI Systems Management API to display the status of Oracle Business Intelligence using either WLST commands or a Java program as described in the following sections:
This example connects a user to Oracle Business Intelligence and displays the service status.
To use WLST commands in a script to display the status of Oracle Business Intelligence:
Open a text editor and create a WLST script similar to the following example:
# Example to demonstrate connecting to a BIEE domain using WLST # # This scripts expects the following arguments: # # 1. wls.host (localhost) # 2. wls.port (7001) # 3. wls.user (user1) # 4. wls.password (password1) # =================================================================== import sys import os # Check the arguments to this script are as expected. # argv[0] is script name. argLen = len(sys.argv) if argLen -1 != 4: print "ERROR: got ", argLen -1, " args." print "USAGE: wlst.cmd wls_connect.py WLS_HOST WLS_PORT WLS_USER WLS_PASSWORD" print " eg: wlst.cmd wls_connect.py localhost 7001 user1 password1" exit() WLS_HOST = sys.argv[1] WLS_PORT = sys.argv[2] WLS_USER = sys.argv[3] WLS_PW = sys.argv[4] print 'Connecting to '+ WLS_HOST+ ':' + WLS_PORT + ' as user: ' + WLS_USER + ' ...' # Connect to WLS connect(WLS_USER, WLS_PW, WLS_HOST+ ':' + WLS_PORT); print 'Connecting to Domain ...' domainCustom() cd ('oracle.biee.admin') print 'Connecting to BIDomain MBean ...' cd ('oracle.biee.admin:type=BIDomain,group=Service') biinstances = get('BIInstances') biinstance = biinstances[0] print 'Connecting to BIInstance MBean ...' cd ('..') cd (biinstance.toString()) servicestatus=get('ServiceStatus') print 'BIInstance MBean; ServiceStatus: ' + servicestatus exit()
Save the script.
Navigate to the folder \MW_HOME\wlserver_10.3\common\bin and run the script, entering any arguments required.
For example, you might enter the following at the command line:
./wlst.sh wlst_connect.py localhost 7001 user1 password
1 (UNIX)
wlst wlst_connect.cmd localhost 7001 user1 password1
(Windows)
The command window (and log file), displays prompts and messages, for example:
Initializing WebLogic Scripting Tool (WLST) ... Welcome to WebLogic Server Administration Scripting Shell Type help() for help on available commands Connecting to localhost:7001 as user: user1 ... Connecting to t3://localhost:7001 with userid password1 ... Successfully connected to Administration Server 'AdminServer' that belongs to domain 'bifoundation_domain'. Warning: An insecure protocol was used to connect to the server. To ensure on-the-wire security, use the SSL port or Admin port instead. Connecting to Domain ... Location changed to domain custom tree. This is a writable tree with No root. For more help, use help(domainCustom) Connecting to BIDomain MBean ... Connecting to BIInstance MBean ... BIInstance MBean; ServiceStatus: FULLY_STARTED Exiting WebLogic Scripting Tool.
For more information about using WLST commands, see Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.
This example connects to Oracle Business Intelligence and displays the current status. The Java program in this example also contains additional methods (commented out) which you can use to start and stop Oracle Business Intelligence. For more information, see Section 22.3.2.2, "Example: Using a Java Program to Stop and Start Oracle Business Intelligence."
To use a Java program with the Systems management API to display the status of Oracle Business Intelligence:
Open a Java editor and compile a Java program similar to the following example:
package com.oracle.bi.example; import java.util.Hashtable; import javax.management.MBeanServerConnection; import javax.management.ObjectName; import javax.management.remote.JMXConnector; import javax.management.remote.JMXConnectorFactory; import javax.management.remote.JMXServiceURL; import javax.naming.Context; /** * Example class showing how to connect to the Oracle BIEE AdminMBeans JMX Interface. * <br/> * This example is intentionally succinct for clarity, so for example, * it does not do any exception handling. * Any production code should include robust error handling. * Note that you need <code>wljmxclient.jar</code> and <code>wlclient.jar</code> on the classpath. */ public class MBeanAPIExample1 { private String host; private int port; private String username; private String password; private MBeanServerConnection mbs = null; private ObjectName biDomainMBeanName; private ObjectName biInstanceMBeanName; private MBeanAPIExample1(String[] args) { if (args.length < 4) { System.out.println("Usage: MBeanAPIExample1 host port username password"); throw new IllegalArgumentException("Not enough arguments"); } host = args[0]; port = Integer.parseInt(args[1]); username = args[2]; password = args[3]; } private void connect() throws Exception { String jmxUrl = "service:jmx:t3://" + host + ":" + port + "/jndi/weblogic.management.mbeanservers.domainruntime"; System.out.println("Connecting using URL: " + jmxUrl + " ..."); Hashtable<String,String> h = new Hashtable<String,String>(); h.put(Context.SECURITY_PRINCIPAL, username); h.put(Context.SECURITY_CREDENTIALS, password); h.put(JMXConnectorFactory.PROTOCOL_PROVIDER_PACKAGES, "weblogic.management.remote"); JMXConnector jmxConnector = JMXConnectorFactory.connect(new JMXServiceURL(jmxUrl), h); mbs = jmxConnector.getMBeanServerConnection(); System.out.println("Connected OK"); biDomainMBeanName = new ObjectName("oracle.biee.admin:type=BIDomain,group=Service"); ObjectName[]biInstanceMBeanNames=(ObjectName[])mbs.getAttribute (biDomainMBeanName, "BIInstances"); biInstanceMBeanName = biInstanceMBeanNames[0]; // there should only be one System.out.println("Found BI Instance MBean: " + biInstanceMBeanName); } private void displayStatus() throws Exception { String status = (String)mbs.getAttribute(biInstanceMBeanName, "ServiceStatus"); System.out.println("Status is: " + status); } private void stopAll() throws Exception { System.out.println("Stopping instance ..."); Object[] args = new Object[]{}; String[] sig = new String[]{}; mbs.invoke(biInstanceMBeanName, "stop", args, sig); System.out.println("Stopped instance OK"); } private void startAll() throws Exception { System.out.println("Starting instance ..."); Object[] args = new Object[]{}; String[] sig = new String[]{}; mbs.invoke(biInstanceMBeanName, "start", args, sig); System.out.println("Started instance OK"); } /** * @param args */ public static void main(String[] args) throws Exception { MBeanAPIExample1 example = new MBeanAPIExample1(args); example.connect(); example.displayStatus(); // example.stopAll(); // example.startAll(); } }
Navigate to the \<wlserver>\server\lib folder and run the Java program, providing the class path, class name and any arguments required.
java -classpath <JavaClassName> <host> <port> <username> <password>
For example:
java -classpath <MW_HOME>wls_10.3/server/lib/wjmxclient.jar com.oracle.bi.example.MBeanAPIExample1 localhost 7001 user1 password1
The command window (and log file) displays prompts and messages, for example:
Connecting using URL: service:jmx:t3://localhost:7001/jndi/weblogic.management.mbeanservers.domainruntime ... Connected OK Found BI Instance MBean: oracle.biee.admin:type=BIDomain.BIInstance,biInstance=coreapplication,group=Service Status is: FULLY_STARTED
You can use the Oracle BI Systems Management API start and stop Oracle Business Intelligence using either WLST commands or a Java program as described in the following sections:
Section 22.3.2.1, "Example: Using WLST Commands to Stop and Start Oracle Business Intelligence"
Section 22.3.2.2, "Example: Using a Java Program to Stop and Start Oracle Business Intelligence"
This example stops and starts the Oracle Business Intelligence instance, and displays the status during each stage of the process.
To use WLST commands to stop and start Oracle Business Intelligence:
Open a text editor and create a WLST script similar to the following:
# Example to demonstrate connecting to a BIEE domain using WLST and stopping and restarting the instance # # This scripts expects the following arguments: # # 1. wls.host (localhost) # 2. wls.port (7001) # 3. wls.user (user1) # 4. wls.password (password1) # =================================================================== import sys import os # Check the arguments to this script are as expected. # argv[0] is script name. argLen = len(sys.argv) if argLen -1 != 4: print "ERROR: got ", argLen -1, " args." print "USAGE: wlst_stop_start.cmd wls_stop_start_obi.py WLS_HOST WLS_PORT WLS_USER WLS_PASSWORD" print " eg: wlst_stop_start.cmd wls_stop_start_obi.py localhost 7001 user1 password1" exit() WLS_HOST = sys.argv[1] WLS_PORT = sys.argv[2] WLS_USER = sys.argv[3] WLS_PW = sys.argv[4] print 'Connecting to '+ WLS_HOST+ ':' + WLS_PORT + ' as user: ' + WLS_USER + ' ...' # Connect to WLS connect(WLS_USER, WLS_PW, WLS_HOST+ ':' + WLS_PORT); print 'Connecting to Domain ...' domainCustom() cd ('oracle.biee.admin') print 'Connecting to BIDomain MBean ...' cd ('oracle.biee.admin:type=BIDomain,group=Service') biinstances = get('BIInstances') biinstance = biinstances[0] print 'Connecting to BIInstance MBean ...' cd ('..') cd (biinstance.toString()) servicestatus=get('ServiceStatus') print 'BIInstance MBean; ServiceStatus: ' + servicestatus print 'Calling stop ...' objs = jarray.array([], java.lang.Object) strs = jarray.array([], java.lang.String) invoke('stop', objs, strs) servicestatus=get('ServiceStatus') print 'BIInstance MBean; ServiceStatus: ' + servicestatus print 'Calling start ...' objs = jarray.array([], java.lang.Object) strs = jarray.array([], java.lang.String) invoke('start', objs, strs) servicestatus=get('ServiceStatus') print 'BIInstance MBean; ServiceStatus: ' + servicestatus exit()
Save the script.
Navigate to the folder \MW_HOME\wlserver_10.3\common\bin and run the script, entering any arguments required.
For example, you might enter the following at the command line:
./wlst.sh wlst_stop_start_obi.py localhost 7001 user1 password
1 (UNIX)
wlst wlst_wlst_stop_start_obi.cmd localhost 7001 user1 password1
(Windows)
The command window (and log file), displays prompts and messages, for example:
Initializing WebLogic Scripting Tool (WLST) ... Welcome to WebLogic Server Administration Scripting Shell Type help() for help on available commands Connecting to localhost:7001 as user: user1 ... Connecting to t3://localhost:7001 with userid password1 ... Successfully connected to Administration Server 'AdminServer' that belongs to domain 'bifoundation_domain'. Warning: An insecure protocol was used to connect to the server. To ensure on-the-wire security, use the SSL port or Admin port instead. Connecting to Domain ... Location changed to domain custom tree. This is a writable tree with No root. For more help, use help(domainCustom) Connecting to BIDomain MBean ... Connecting to BIInstance MBean ... BIInstance MBean; ServiceStatus: FULLY_STARTED Calling stop ... BIInstance MBean; ServiceStatus: STOPPED Calling start ... BIInstance MBean; ServiceStatus: FULLY_STARTED Exiting WebLogic Scripting Tool.
Refer to the example in Section 22.3.1.2, "Example: Using a Java Program to Display the Status of Oracle Business Intelligence," remove the comments (/) before whichever method you want to run (example.stopAll(); or example.startAll();), as shown in the following main method:
/** * @param args */ public static void main(String[] args) throws Exception { MBeanAPIExample1 example = new MBeanAPIExample1(args); example.connect(); example.displayStatus(); /** example.stopAll(); */ /** example.startAll(); */ }
You can use the Oracle BI Systems Management API to change Oracle Business Intelligence configuration settings using WLST commands or a Java program as follows:
You can copy the examples in this section, replacing MBean details with details of other MBeans to update different Oracle Business Intelligence configuration settings (for example, log file settings, security settings). For more information, see Section 22.4, "Descriptions of JMX Admin MBeans and Methods for the Oracle BI Systems Management API."
This example connects to Oracle Business Intelligence, invokes the system lock, updates the value of the Email Sender Display Name configuration setting, and releases the system lock.
To use WLST to update the Email Sender Display Name configuration setting:
Open a text editor and enter WLST commands similar to the following:
# Example to demonstrate connecting to a BIEE domain using WLST, # and changing a simple configuration setting # # This script expects the following arguments: # # 1. wls.host (localhost) # 2. wls.port (7001) # 3. wls.user (user1) # 4. wls.password (password1) # 5. new email displayname # =================================================================== import sys import os # Check the arguments to this script are as expected. # argv[0] is script name. argLen = len(sys.argv) if argLen -1 != 5: print "ERROR: got ", argLen -1, " args." print "USAGE: wlst.cmd wls_connect.py WLS_HOST WLS_PORT WLS_USER WLS_PASSWORD EmailDisplayName" print " eg: wlst.cmd wls_connect.py localhost 7001 user1 password1 FredBloggs" exit() WLS_HOST = sys.argv[1] WLS_PORT = sys.argv[2] WLS_USER = sys.argv[3] WLS_PW = sys.argv[4] newDisplayName = sys.argv[5] print 'Connecting to '+ WLS_HOST+ ':' + WLS_PORT + ' as user: ' + WLS_USER + ' ...' # Connect to WLS connect(WLS_USER, WLS_PW, WLS_HOST+ ':' + WLS_PORT); print 'Connecting to Domain ...' domainCustom() cd ('oracle.biee.admin') print 'Connecting to BIDomain MBean ...' cd ('oracle.biee.admin:type=BIDomain,group=Service') #bidomain=cmo print 'Calling lock ...' objs = jarray.array([], java.lang.Object) strs = jarray.array([], java.lang.String) invoke('lock', objs, strs) biinstances = get('BIInstances') biinstance = biinstances[0] print 'Connecting to BIInstance MBean ...' cd ('..') cd (biinstance.toString()) servicestatus=get('ServiceStatus') print 'BIInstance MBean; ServiceStatus: ' + servicestatus biemailbean = get('EmailConfiguration') print 'Connecting to BIInstance Email MBean ...' cd ('..') cd (biemailbean.toString()) oldDisplayName=get('SenderDisplayName') print 'Existing email displayname is: ' + oldDisplayName print 'Changing email displayname to: ' + newDisplayName + ' ...' set('SenderDisplayName', newDisplayName) print 'Calling commit ...' cd ('..') cd ('oracle.biee.admin:type=BIDomain,group=Service') objs = jarray.array([], java.lang.Object) strs = jarray.array([], java.lang.String) invoke('commit', objs, strs) print 'Committed OK' exit()
Save the script.
Navigate to the folder \MW_HOME\wlserver_10.3\common\bin and run the script, entering any arguments required.
For example, you might enter the following at the command line:
./wlst.sh wlst_email_disp_name_obi.py localhost 7001 user1 password
1 (UNIX)
wlst wlst_wlst_email_disp_name_obi.cmd localhost 7001 user1 password1
(Windows)
The command window (and log file) displays prompts and messages, for example:
Initializing WebLogic Scripting Tool (WLST) ... Welcome to WebLogic Server Administration Scripting Shell Type help() for help on available commands Connecting to localhost:7001 as user: user1 ... Connecting to t3://localhost:7001 with userid password1 ... Successfully connected to Administration Server 'AdminServer' that belongs to domain 'bifoundation_domain'. Warning: An insecure protocol was used to connect to the server. To ensure on-the-wire security, use the SSL port or Admin port instead. Connecting to Domain ... Location changed to domain custom tree. This is a writable tree with No root. For more help, use help(domainCustom) Connecting to BIDomain MBean ... Connecting to BIInstance MBean ... BIInstance MBean; ServiceStatus: FULLY_STARTED Connecting to BIInstance Email MBean ... Existing email displayname is: Oracle Business Intelligence Changing email displayname to: FredBloggs ... Calling commit ... Committed OK Exiting WebLogic Scripting Tool.
To use a Java program to Edit the Email Sender Display Name Configuration Setting:
Open a Java editor and compile a Java program similar to the following example:
package com.oracle.bi.example; import java.util.Hashtable; import javax.management.Attribute; import javax.management.MBeanServerConnection; import javax.management.ObjectName; import javax.management.remote.JMXConnector; import javax.management.remote.JMXConnectorFactory; import javax.management.remote.JMXServiceURL; import javax.naming.Context; /** * Example class showing how to connect to the Oracle BIEE AdminMBeans JMX Interface and change a simple configuration setting.. * <br/> * This example is intentionally succinct for clarity, so for example, * it does not do any exception handling. * Any production code should include robust error handling. * * Note that you need <code>wljmxclient.jar</code> and <code>wlclient.jar</code> on the classpath. */ public class MBeanAPIExample3Edit { private String host; private int port; private String username; private String password; private String newDisplayName; private MBeanServerConnection mbs = null; private ObjectName biDomainMBeanName; private ObjectName biInstanceMBeanName; private ObjectName biEmailMBeanName; private MBeanAPIExample3Edit(String[] args) { if (args.length < 5) { System.out.println("Usage: MBeanAPIExample3Edit host port username password newDisplayName"); throw new IllegalArgumentException("Not enough arguments"); } host = args[0]; port = Integer.parseInt(args[1]); username = args[2]; password = args[3]; newDisplayName = args[4]; } private void connect() throws Exception { String jmxUrl = "service:jmx:t3://" + host + ":" + port + "/jndi/weblogic.management.mbeanservers.domainruntime"; System.out.println("Connecting using URL: " + jmxUrl + " ..."); Hashtable<String,String> h = new Hashtable<String,String>(); h.put(Context.SECURITY_PRINCIPAL, username); h.put(Context.SECURITY_CREDENTIALS, password); h.put(JMXConnectorFactory.PROTOCOL_PROVIDER_PACKAGES, "weblogic.management.remote"); JMXConnector jmxConnector = JMXConnectorFactory.connect(new JMXServiceURL(jmxUrl), h); mbs = jmxConnector.getMBeanServerConnection(); System.out.println("Connected OK"); biDomainMBeanName = new ObjectName("oracle.biee.admin:type=BIDomain,group=Service"); ObjectName[]biInstanceMBeanNames=(ObjectName[])mbs.getAttribute (biDomainMBeanName, "BIInstances"); biInstanceMBeanName = biInstanceMBeanNames[0]; // there should only be one System.out.println("Found BI Instance MBean: " + biInstanceMBeanName); } private void lock() throws Exception{ System.out.println("Locking domain ..."); Object[] args = new Object[]{}; String[] sig = new String[]{}; mbs.invoke(biDomainMBeanName, "lock", args, sig); System.out.println("Locked domain OK"); } private void commit() throws Exception{ System.out.println("Committing changes ..."); Object[] args = new Object[]{}; String[] sig = new String[]{}; mbs.invoke(biDomainMBeanName, "commit", args, sig); System.out.println("Committed changes OK"); } private void getEmailBean() throws Exception{ System.out.println("Getting Email MBean ..."); biEmailMBeanName = (ObjectName)mbs.getAttribute(biInstanceMBeanName, "EmailConfiguration"); System.out.println("Found BI Email MBean: " + biEmailMBeanName); } private void updateEmailDisplayName() throws Exception { String oldDisplayName = (String)mbs.getAttribute(biEmailMBeanName, "SenderDisplayName"); System.out.println("Existing email displayname is: " + oldDisplayName); System.out.println("Changing email displayname to: " + newDisplayName); mbs.setAttribute(biEmailMBeanName, new Attribute("SenderDisplayName", newDisplayName)); } /** * @param args */ public static void main(String[] args) throws Exception { MBeanAPIExample3Edit example = new MBeanAPIExample3Edit(args); example.connect(); example.getEmailBean(); example.lock(); example.updateEmailDisplayName(); example.commit(); } }
Navigate to the \<wlserver>\server\lib folder and run the Java program giving the class path, class name and any arguments required.
java -classpath <JavaClassName> <host> <port> <username> <password> <SenderDisplayName>
For example:
java -classpath <MW_HOME>wls_10.3/server/lib/wjmxclient.jar com.oracle.bi.example.MBeanAPIExample3Edit localhost 7001 user1 password1 FredBloggs
Use quotation marks to include spaces, for example "Fred Bloggs".
The command window (and log file), displays prompts and messages, for example:
Connecting using URL: service:jmx:t3://localhost:7001/jndi/weblogic.management.mbeanservers.domainruntime ... Connected OK Found BI Instance MBean: oracle.biee.admin:type=BIDomain.BIInstance,biInstance=coreapplication,group=Service Getting Email MBean ... Found BI Email MBean: oracle.biee.admin:type=BIDomain.BIInstance.EmailConfiguration,biInstance=coreapplication,group=Service Locking domain ... Locked domain OK Existing email displayname is: Oracle Business Intelligence Changing email displayname to: FredBloggs Committing changes ... Committed changes OK
You can use the Oracle BI Systems Management API to scale out to additional host computers for high availability and performance. Use the Enterprise Install to install Oracle Business Intelligence onto a new host computer, and then scale out using steps similar to those described in the following examples:
Section 22.3.4.1, "Example: Using WLST to Scale Out to Servers"
Section 22.3.4.2, "Example: Using a Java Program to Scale Out to Servers"
This example connects a user to Oracle Business Intelligence and scales out to a server.
To use WLST commands in a script to scale out to servers:
Open a text editor and create a WLST script similar to the following example:
# Example to demonstrate connecting to a BIEE domain using WLST # and do some scale-out operations. # # This scripts expects the following arguments: # # 1. wls.host (localhost) # 2. wls.port (7001) # 3. wls.user (user1) # 4. wls.password (password1) # 5. oracle instance name# 6. new count of bi servers # =================================================================== import sys import os # Check the arguments to this script are as expected. # argv[0] is script name. argLen = len(sys.argv) if argLen -1 != 6: print "ERROR: got ", argLen -1, " args." print "USAGE: wlst.cmd wls_connect.py WLS_HOST WLS_PORT WLS_USER WLS_PASSWORD" OracleInstance numBIServers print " eg: wlst.cmd wls_connect.py localhost 7001 user1 password1 instance2 2" exit() WLS_HOST = sys.argv[1] WLS_PORT = sys.argv[2] WLS_USER = sys.argv[3] WLS_PW = sys.argv[4] oracleInstanceName = sys.argv[5] # convert string to int which is needed later newNumBIServers = int(sys.argv[6]) print 'Connecting to '+ WLS_HOST+ ':' + WLS_PORT + ' as user: ' + WLS_USER + ' ...' # Connect to WLS connect(WLS_USER, WLS_PW, WLS_HOST+ ':' + WLS_PORT); print 'Connecting to Domain ...' domainCustom() cd ('oracle.biee.admin') print 'Connecting to BIDomain MBean ...' cd ('oracle.biee.admin:type=BIDomain,group=Service') biinstances = get('BIInstances') biinstance = biinstances[0] oracleinstances = get('OracleInstances') print 'Connecting to BIInstance MBean ...' cd ('..') print 'About to cd to: ' + biinstance.toString() cd (biinstance.toString()) servicestatus=get('ServiceStatus') print 'BIInstance MBean; ServiceStatus: ' + servicestatus print 'Looping through OracleInstances looking for: ' + oracleInstanceName matching = false for oi in oracleinstances: cd('..') print 'About to cd to: ' + oi.toString() cd ( oi.toString() ) id = get('Id') print 'Found instance with id: ' + id if id == oracleInstanceName: matching = oi break if matching : print 'Found matching OracleInstance...' else : print 'Failed to find target OracleInstance with name: ' + oracleInstanceName exit() deployments = get('BIInstanceDeployments') # Should only ever be one of these deployment = deployments[0] print 'Acquired BIInstanceDeployment : ' + deployment.toString() cd('..') cd ('oracle.biee.admin:type=BIDomain,group=Service') print 'Calling lock ...' objs = jarray.array([], java.lang.Object) strs = jarray.array([], java.lang.String) invoke('lock', objs, strs) cd('..') cd(deployment.toString()) numBIServers = get('numBIServers') print 'Current number of BI Servers is:', numBIServers print 'About to set number of BI Servers to:', newNumBIServers set('numBIServers', newNumBIServers ) print 'Successfully set number of BI Servers to', newNumBIServers print 'Calling commit ...' cd ('..') cd ('oracle.biee.admin:type=BIDomain,group=Service') objs = jarray.array([], java.lang.Object) strs = jarray.array([], java.lang.String) invoke('commit', objs, strs) print 'Committed OK' print 'Connecting to BIInstance MBean ...' cd ('..') cd (biinstance.toString()) servicestatus=get('ServiceStatus') print 'BIInstance MBean; ServiceStatus: ' + servicestatus print 'Calling stop ...' objs = jarray.array([], java.lang.Object) strs = jarray.array([], java.lang.String) invoke('stop', objs, strs) servicestatus=get('ServiceStatus') print 'BIInstance MBean; ServiceStatus: ' + servicestatus print 'Calling start ...' objs = jarray.array([], java.lang.Object) strs = jarray.array([], java.lang.String) invoke('start', objs, strs) servicestatus=get('ServiceStatus') print 'BIInstance MBean; ServiceStatus: ' + servicestatus exit()
Save the script.
Navigate to the folder \MW_HOME\wlserver_10.3\common\bin and run the script, entering any arguments required.
For example, you might enter the following at the command line:
./wlst.sh wlst_scaleout_obi.py localhost 7001 user1 password
1 (UNIX)
wlst wlst_wlst_scaleout_obi.cmd localhost 7001 user1 password1
(Windows)
The command window (and log file), displays prompts and messages, for example:
Initializing WebLogic Scripting Tool (WLST) ... Welcome to WebLogic Server Administration Scripting Shell Type help() for help on available commands Connecting to localhost:7001 as user: user1 ... Connecting to t3://localhost:7001 with userid password1 ... Successfully connected to Administration Server 'AdminServer' that belongs to domain 'bifoundation_domain'. Warning: An insecure protocol was used to connect to the server. To ensure on-the-wire security, use the SSL port or Admin port instead. Connecting to Domain ... Location changed to domain custom tree. This is a writable tree with No root. For more help, use help(domainCustom) Connecting to BIDomain MBean ... Connecting to BIInstance MBean ... About to cd to: oracle.biee.admin:type=BIDomain.BIInstance,biInstance=coreapplication,group=Service BIInstance MBean; ServiceStatus: FULLY_STARTED Looping through OracleInstances looking for: instance1 About to cd to: oracle.biee.admin:oracleInstance=instance1,type=BIDomain.OracleInstance,group=Service Found instance with id: instance1 Found matching OracleInstance... Acquired BIInstanceDeployment : oracle.biee.admin:oracleInstance=instance1,type=BIDomain.OracleInstance.BIInstanceDeployment,biInstance=coreapplication,group=Service Calling lock ... Current number of BI Servers is: 1 About to set number of BI Servers to: 6 Successfully set number of BI Servers to 6 Calling commit ... Committed OK Connecting to BIInstance MBean ... BIInstance MBean; ServiceStatus: PARTIALLY_STARTED Calling stop ... BIInstance MBean; ServiceStatus: PARTIALLY_STARTED Calling start ... BIInstance MBean; ServiceStatus: FULLY_STARTED Exiting WebLogic Scripting Tool.
For more information about using WLST commands, see Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.
To use a Java program to scale out to servers:
Open a Java editor and compile a Java program similar to the following example:
package com.oracle.bi.example; import java.util.Hashtable; import javax.management.Attribute; import javax.management.MBeanServerConnection; import javax.management.ObjectName; import javax.management.remote.JMXConnector; import javax.management.remote.JMXConnectorFactory; import javax.management.remote.JMXServiceURL; import javax.naming.Context; /** * Example class showing how to connect to the Oracle BIEE AdminMBeans JMX Interface, * and do some scale-out operations. * <br/> * This example is intentionally succinct for clarity, so for example, * it does not do any exception handling. * Any production code should include robust error handling. * <br/> * Note that you need <code>wljmxclient.jar</code> and <code>wlclient.jar</code> on the classpath. */ public class MBeanAPIExample4ScaleOut { private String host; private int port; private String username; private String password; private String oracleInstanceName; private int newNumBIServers; private MBeanServerConnection mbs = null; private ObjectName biDomainMBeanName; private ObjectName biInstanceMBeanName; private ObjectName[] oracleInstanceMBeanNames; private MBeanAPIExample4ScaleOut(String[] args) { if (args.length < 6) { System.out.println("Usage: MBeanAPIExample1Connect host port username password oracleInstanceName NumBIServers"); throw new IllegalArgumentException("Not enough arguments"); } host = args[0]; port = Integer.parseInt(args[1]); username = args[2]; password = args[3]; oracleInstanceName = args[4]; newNumBIServers = Integer.parseInt(args[5]); } private void connect() throws Exception { String jmxUrl = "service:jmx:t3://" + host + ":" + port + "/jndi/weblogic.management.mbeanservers.domainruntime"; System.out.println("Connecting using URL: " + jmxUrl + " ..."); Hashtable<String,String> h = new Hashtable<String,String>(); h.put(Context.SECURITY_PRINCIPAL, username); h.put(Context.SECURITY_CREDENTIALS, password); h.put(JMXConnectorFactory.PROTOCOL_PROVIDER_PACKAGES, "weblogic.management.remote"); JMXConnector jmxConnector = JMXConnectorFactory.connect(new JMXServiceURL(jmxUrl), h); mbs = jmxConnector.getMBeanServerConnection(); System.out.println("Connected OK"); biDomainMBeanName = new ObjectName("oracle.biee.admin:type=BIDomain,group=Service"); ObjectName[] biInstanceMBeanNames = (ObjectName[])mbs.getAttribute(biDomainMBeanName, "BIInstances"); biInstanceMBeanName = biInstanceMBeanNames[0]; // there should only be one System.out.println("Found BI Instance MBean: " + biInstanceMBeanName); oracleInstanceMBeanNames = (ObjectName[])mbs.getAttribute(biDomainMBeanName, "OracleInstances"); for (ObjectName oracleInstanceMBeanName : oracleInstanceMBeanNames) { System.out.println("Found Oracle Instance MBean: " + oracleInstanceMBeanName); } } private void displayStatus() throws Exception { String status = (String)mbs.getAttribute(biInstanceMBeanName, "ServiceStatus"); System.out.println("Status is: " + status); } private void lock() throws Exception { System.out.println("Locking domain ..."); Object[] args = new Object[]{}; String[] sig = new String[]{}; mbs.invoke(biDomainMBeanName, "lock", args, sig); System.out.println("Locked domain OK"); } private void commit() throws Exception { System.out.println("Committing changes ..."); Object[] args = new Object[]{}; String[] sig = new String[]{}; mbs.invoke(biDomainMBeanName, "commit", args, sig); System.out.println("Committed changes OK"); } private ObjectName findMatchingOracleInstanceMBean() throws Exception { for (ObjectName oracleInstanceMBeanName : oracleInstanceMBeanNames) { String oracleInstanceId = (String)mbs.getAttribute(oracleInstanceMBeanName, "Id"); if (oracleInstanceId.equals(oracleInstanceName)) { return oracleInstanceMBeanName; } } throw new RuntimeException("Cannot find oracle instance: " + oracleInstanceName); } private void scaleOut(ObjectName oracleInstanceMBeanName) throws Exception { ObjectName[] biInstanceDeploymentMBeanNames = (ObjectName[])mbs.getAttribute(oracleInstanceMBeanName, "BIInstanceDeployments"); ObjectName biInstanceDeploymentMBeanName = biInstanceDeploymentMBeanNames[0]; // there should only be one System.out.println("Found BI Instance Deployment MBean: " + biInstanceDeploymentMBeanName); int numBIServers = (Integer)mbs.getAttribute(biInstanceDeploymentMBeanName, "NumBIServers"); System.out.println("Found Num BI Servers: " + numBIServers); System.out.println("Setting Num BI Servers to: " + newNumBIServers); mbs.setAttribute(biInstanceDeploymentMBeanName, new Attribute("NumBIServers", newNumBIServers)); } private void stopAll() throws Exception { System.out.println("Stopping instance ..."); Object[] args = new Object[]{}; String[] sig = new String[]{}; mbs.invoke(biInstanceMBeanName, "stop", args, sig); System.out.println("Stopped instance OK"); } private void startAll() throws Exception { System.out.println("Starting instance ..."); Object[] args = new Object[]{}; String[] sig = new String[]{}; mbs.invoke(biInstanceMBeanName, "start", args, sig); System.out.println("Started instance OK"); } public static void main(String[] args) throws Exception { MBeanAPIExample4ScaleOut example = new MBeanAPIExample4ScaleOut(args); example.connect(); example.displayStatus(); ObjectName oiMBeanName = example.findMatchingOracleInstanceMBean(); example.lock(); example.scaleOut(oiMBeanName); example.commit(); example.stopAll(); example.startAll(); example.displayStatus(); } }
Navigate to the \<wlserver>\server\lib folder and run the Java program, providing the class name and any arguments required.
For example:
java <JavaClassName> <host> <port> <username> <password> <oracleInstanceName> <newNumBIServers>
Navigate to the \<wlserver>\server\lib folder and run the Java program, providing the class path, class name, and any arguments required.
java -classpath <JavaClassName> <host> <port> <username> <password> <oracleInstanceName> <newNumBIServers>
For example:
java -classpath <MW_HOME>wls_10.3/server/lib/wjmxclient.jar com.oracle.bi.example.MBeanAPIExample4ScaleOut localhost 7001 user1 password1 instance1 3
The command window (and log file) displays prompts and messages, for example:
Connecting using URL: service:jmx:t3://localhost:7001/jndi/weblogic.management.mbeanservers.domainruntime ... Connected OK Found BI Instance MBean: oracle.biee.admin:type=BIDomain.BIInstance,biInstance=coreapplication,group=Service Found Oracle Instance MBean: oracle.biee.admin:oracleInstance=instance1,type=BIDomain.OracleInstance,group=Service Status is: PARTIALLY_STARTED Locking domain ... Locked domain OK Found BI Instance Deployment MBean: oracle.biee.admin:oracleInstance=instance1,type=BIDomain.OracleInstance.BIInstanceDeployment,biInstance=coreapplication,group=Service Found Num BI Servers: 1 Setting Num BI Servers to: 3 Committing changes ... Committed changes OK Stopping instance ... Stopped instance OK Starting instance ... Started instance OK Status is: FULLY_STARTED
In addition to the Metrics Browser in Fusion Middleware Control, you can view metrics for Oracle Business Intelligence using the Dynamic Monitoring Service (DMS) and WLST commands. This section describes how to use these methods.
You can use the Dynamic Monitoring Service (DMS) to view metrics for Oracle Business Intelligence. Access the service using the following URL:
http://<
host
>:7001/dms
Using the Metrics Tables list in the left pane, select Non-J2EE Metrics to view the list of metrics for Oracle Business Intelligence. This is the same list that you see in the Metrics Browser of Fusion Middleware Control.
You can use the Dynamic Monitoring Service to quickly obtain a snapshot of metrics. You can use the URL for a given metric as the source for a web query in a Microsoft Excel spreadsheet that you combine with a macro that automatically copies values to an archive sheet and refreshes the query on a loop for a given period.
Suppose that you want to use the Dynamic Monitoring Service to see the details of the metric table called "Oracle_BI_General". When you click the Oracle_BI_General link in the Metrics Tables list, the table is displayed on the right side. This metric table consists of several monitored values, such as Active_Execute_Requests and Total_Sessions. You can use the information from the tables that are displayed in this Metrics Browser as part of WLST commands.
For information on accessing DMS metrics using WLST commands, see the chapter on DMS custom WLST commands in Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.
You can use WLST commands to capture metrics for Oracle Business Intelligence.
To use WLST commands for metrics:
Navigate to the MW_HOME/ORACLE_HOME/common/bin directory.
Run the WLST utility.
Connect to the Oracle BI system using the connect command, as shown in the following example:
connect('
user
','
password
','t3://<
host
>:7001')
Verify that you are in "online mode" by viewing the following prompt:
wls:/bifoundation_domain/serverConfig>
You can now interactively use the DMS custom WLST commands. For example, to list all the metric tables that start with "Oracle_BI", enter the following command:
wls:/bifoundation_domain/serverConfig> displayMetricTables('Oracle_BI*')
This command generates a long list of data for each of the Oracle BI metric tables. So it is more useful to focus on a given metric table, such as "Oracle_BI_General". The following command displays output such as that shown in this sample.
wls:/bifoundation_domain/serverConfig> displayMetricTables('Oracle_BI_General')
----------------- Oracle_BI_General ----------------- Active_Execute_Requests.value: 0 Active_Fetch_Requests.value: 0 Active_File_Handles.value: 1 Active_Initblock_Executions.value: 0 Active_Logins.value: 0 Active_Prepare_Requests.value: 0 Avg._Failed_Logins_Elapsed_Time.value: 0 Avg._Initblock_Executions_Elapsed_Time.value: 0 Avg._Succeeded_Logins_Elapsed_Time.value: 0 Avg._query_elapsed_time.value: 0 Busy_File_Handles.value: 0 File_Handle_Waiters.value: 0 Free_File_Handles.value: 502 Host: oracle-bc5ac6af Max._Initblock_Execution_Elapsed_Time.value: 0 Max_File_Handles.value: 503 Name: Oracle BI General New_Execute_Requests.value: 19 New_Fetch_Requests.value: 32 New_Initblock_Executions.value: 0 New_Logins.value: 7 New_Prepare_Requests.value: 19 New_Requests.value: 187 OBPERF_***.value: 7 Oracle_BI_Applications: Oracle BI Server Parent: /Oracle BI Server Process: Oracle BI Server:4004:/instance1/coreapplication_obis1 Queries/sec.value: 0 ServerName: /instance1/coreapplication_obis1 Succeeded_Initblock_Execution_Ratio_as_%.value: 0 Succeeded_Logins_Ratio_as_%.value: 7 Total_sessions.value: 0
Using the scripting capability of WLST, you can embed DMS commands into a Jython script to store the required metric values in a file. The following is an example of such a script.
# Script to dump timestamp (in milliseconds) for a single Oracle BI metric # to a file # from java.util import Date from java.text import SimpleDateFormat # # Modify to connect to your server connect('biadmin','welcome1','t3://localhost:7001') # # This is the number of times to sample the metric sample_length = 100 # # This is where you define what metric table and metric to dump to file metric_table = "Oracle_BI_General" metric_of_interest = "Avg._query_elapsed_time.value" # # Some metrics have non-text characters in the name. Provide a reference here # so it dumps to file without error in file name output_file_metric_ref = "Avg_Qry_Elapse" # # This section defines the output file name with unique time start_time = str(SimpleDateFormat("dd-MMM-yyyy_HH-mm-ss").format(Date())) output_filename = start_time + "_" + output_file_metric_ref + "_dump.txt" # # Open the file and write summary of metric to be dumped file = open(output_filename,'w') print >>file, "Start Metric Dump of: " + str(metric_table) + " : " + str(metric_of_interest) + " at " + str(SimpleDateFormat("dd-MMM-yyyy HH-mm-ss").format(Date())) # # # The following section forms a loop according to the sample length defined # earlier. The 'displayMetricTables()' command returns the metric table in the # form of a JMX composite data array. The code following this command access # the metric data from this array. In this case, a particular metric of # interest is tested for and only the value of that metric is output to file. # counter = 0 while counter <= sample_length: results = displayMetricTables(metric_table) for table in results: name = table.get('Table') rows = table.get('Rows') rowCollection = rows.values() iter = rowCollection.iterator() while iter.hasNext(): row = iter.next() rowType = row.getCompositeType() keys = rowType.keySet() keyIter = keys.iterator() while keyIter.hasNext(): columnName = keyIter.next() value = row.get(columnName) if columnName == metric_of_interest: print >>file, str(SimpleDateFormat("dd-MMM-yyyy HH-mm-ss-SSS").format(Date())) + "," + str(value) counter = counter + 1 file.close() disconnect()
Certain Oracle BI metric tables, such as "Oracle_BI_Thread_Pool", are in effect two-dimensional. With the "Oracle_BI_Thread_Pool" table, you can query the metric values for various "Names", such as "Server" or "Usage_Tracking". To export the required metric value to a file in this case, you must modify the logic that was used in looping in the previous example script to handle the two dimensions. The following example script provides one way to handle this case.
# Script to dump timestamp (in milliseconds) and a #single Oracle BI metric to a file for metrics with multiple sections # from java.util import Date from java.text import SimpleDateFormat # # Modify to connect to your server connect('biadmin','welcome1','t3://localhost:7001') # # This is the number of times to sample the metric sample_length = 100 # # This is where you define what metric table, category, and metric to # dump to file metric_table = "Oracle_BI_Thread_Pool" category_of_interest = "Server" metric_of_interest = "Avg._Request/sec.value" # # Some metrics have non-text characters - provide a reference here # so it dumps to file without error output_file_metric_ref = "Avg_Req_Sec" # # This section defines the output file name with unique time start_time = str(SimpleDateFormat("dd-MMM-yyyy_HH-mm-ss").format(Date())) output_filename = start_time + "_" + output_file_metric_ref + "_dump.txt" # # Open the file and write summary of metric to be dumped file = open(output_filename,'w') print >>file, "Start Metric Dump of: " + str(metric_table) + " : " + str(metric_of_interest) + " for Category: " + str(category_of_interest) + " at " + str(SimpleDateFormat("dd-MMM-yyyy HH-mm-ss").format(Date())) # # counter = 0 while counter <= sample_length: results = displayMetricTables(metric_table) for table in results: name = table.get('Table') rows = table.get('Rows') rowCollection = rows.values() iter = rowCollection.iterator() while iter.hasNext(): row = iter.next() if row.containsValue(category_of_interest): rowType = row.getCompositeType() keys = rowType.keySet() keyIter = keys.iterator() while keyIter.hasNext(): columnName = keyIter.next() value = row.get(columnName) if columnName == metric_of_interest: print >>file, str(SimpleDateFormat("dd-MMM-yyyy HH-mm-ss-SSS").format(Date())) + "," + str(value) counter = counter + 1 file.close() disconnect()
This section lists the JMX Admin MBeans of the Oracle BI Systems Management API that you use to perform system administration tasks (using WLST scripts and Java programs). Your code must reference Admin MBeans and their attributes and methods. This section lists the Admin MBeans. The JavaDoc pages describe the attributes and methods that are available for each Admin MBean.
For example, display the JavaDoc files in a web browser and click the Admin MBean EmailConfigurationMBean. You see all related attributes and methods, and you can then use the correct attribute and method names in WLST scripts or Java programs.
See the JavaDoc file that is located in the following directory:
ORACLE_HOME/doc/javadoc/bifoundation/jmxapi/index.html
Table 22-1 lists the JMX Admin MBeans for the Oracle BI Systems Management API.
Table 22-1 Oracle BI Systems Management API JMX Admin MBeans
Admin MBean | Description |
---|---|
AvailabilityConfigurationMBean |
Provides an MBean interface for configuring several options that affect process availability for Oracle Business Intelligence. |
BIComponentMBean |
Defines an MBean interface for a component of a BI domain. |
BIDomainMBean |
Defines an MBean interface for managing a BI domain. |
BIInstanceDeploymentMBean |
Defines an MBean interface to describe the deployment (provisioning) of system components to an Oracle instance. |
BIInstanceMBean |
Defines an MBean interface for managing system components. |
BILogConfigurationMBean |
Defines an MBean interface for managing Oracle Business Intelligence log file settings and levels. |
BISizeAgeLogConfigurationMBean |
Defines an MBean interface for managing query log file settings. |
EmailConfigurationMBean |
Defines an MBean interface for managing the email configuration of system components. |
MarketingConfigurationMBean |
Defines an MBean interface for managing the marketing configuration of system components. |
OracleInstanceMBean |
Defines an MBean interface for managing an Oracle instance. |
PerformanceConfigurationMBean |
Defines an MBean interface for managing the performance configuration of system components. |
PresentationConfigurationMBean |
Defines an MBean interface for managing the presentation configuration of system components. |
PresentationServerConfigurationMBean |
Defines an MBean interface for managing the configuration of Presentation Services. |
ScaleOutSupportMBean |
Provides operations to support scaling out a domain. |
SchedulerDatabaseMBean |
Defines an MBean interface for managing Scheduler database connection settings. |
SecurityConfigurationMBean |
Defines an MBean interface for managing the centralized security configuration of system components. |
ServerConfigurationMBean |
Defines an MBean interface for managing settings related to the Oracle BI Server. |
You can also use the MBean Browser to access Admin MBeans. For information, see Section 2.4, "Managing Oracle Business Intelligence JMX MBeans Using the Fusion Middleware Control MBean Browser."