Interface WebClusterAdmin
-
public interface WebClusterAdmin
WebClusterAdmin is an interface from which a user can connect to or disconnect from an Intelligence Server Cluster, monitor the Intelligence Server Clusters the API is currently connecting to, monitor the connection pool used to connect the API and the Intelligence Servers and set the connection pool size to tune the performance.- Since:
- MicroStrategy Web 7.3.1 or earlier
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description WebClusterNode
connect(java.lang.String nodeName, int port)
WebClusterNode
connect(java.lang.String nodeName, int port, int initialPoolSize)
WebClusterNode
connect(java.lang.String nodeName, int port, int initialPoolSize, int maxPoolSize)
Connects the Web API to an Intelligence Server cluster.void
disconnect(java.lang.String nodeName)
This method is used to disconnect from an Intelligence Server Cluster.boolean
getAutoConnect()
Returns the current autoConnect setting on the XMLAPI.WebCluster
getCluster(java.lang.String nodeName)
This method returns aWebCluster
interface for a given node name.WebClusterInfos
getClusterInfos()
WebClusterNode
getClusterNode(java.lang.String nodeName)
Returns anWebClusterNode
interface for a given node name.WebClusters
getClusters()
This method returns a collection of Intelligence Server Clusters representing all clusters that the API is connected to.boolean
getEncryption()
Returns whether the API is set to use encryption when talking to the Intelligence Server.EncryptionMode
getEncryptionMode()
Returns the currentEncryptionMode
configured.boolean
getKeepAlive()
Returns the keepAlive setting on the XMLAPI.int
getRequestTimeOutMillis()
Returns the number of milliseconds that the Web API will wait for a Server to respond to a request.int
getServerBusyTimeOutMillis()
Returns the number of milliseconds that a request waits for a "free" connection before returning the "Server too busy" error message.void
refreshAllClusters()
Refreshes all clusters that the Web API is connected to.void
refreshCluster(java.lang.String nodeName)
Refreshes the cluster information that the API returns.void
setAutoConnect(boolean autoConnect)
Sets the autoConnect setting on the XMLAPI.void
setEncryption(boolean encryption)
Sets whether the API should use encryption when talking to the Intelligence Server.void
setEncryptionMode(EncryptionMode mode)
Sets whether the API should use encryption when talking to the Intelligence Server, and the nature of the encryption mode.void
setInitConnectionPoolFailureTolerance(int connectionFailureTolerance)
sets the number of times that the Web API could fail for initialize the connection pool.void
setKeepAlive(boolean keepAlive)
Sets the keepAlive setting on the XMLAPI.void
setRequestTimeOutMillis(int newTimeoutMillis)
Sets the number of milliseconds that the Web API will wait for a Server to respond to a request.void
setServerBusyTimeOutMillis(int newTimeout)
Sets the number of milliseconds that a request waits for a "free" connection before returning the "Server too busy" error message.
-
-
-
Method Detail
-
connect
WebClusterNode connect(java.lang.String nodeName, int port, int initialPoolSize) throws WebObjectsException
- Parameters:
nodeName
- The name of the cluster node(Intelligence Server name).port
- The port number that the Intelligence Server is listening on. [Default=0]initialPoolSize
- The initial size of the connection pool. [Default=4]- Returns:
- A
WebClusterNode
object used to connect to the Server. - Throws:
WebObjectsException
- Signals an error condition while connecting to an Intelligence Server cluster.- See Also:
connect(String, int, int, int)
-
connect
WebClusterNode connect(java.lang.String nodeName, int port) throws WebObjectsException
- Parameters:
nodeName
- The name of the cluster node(Intelligence Server name).port
- The port number that the Intelligence Server is listening on. [Default=0]- Returns:
- A
WebClusterNode
object used to connect to the Server. - Throws:
WebObjectsException
- Signals an error condition while connecting to an Intelligence Server cluster.- See Also:
connect(String, int, int, int)
-
connect
WebClusterNode connect(java.lang.String nodeName, int port, int initialPoolSize, int maxPoolSize) throws WebObjectsException
Connects the Web API to an Intelligence Server cluster.A connection is a TCP/IP connection between a Web API and a DSS Server. It is used by the API to pass a request (create session request, execute report request etc.) to and retrieve the response from the DSS Server.
The method establishes the connection pool for a given DSS Server Cluster. The NodeName is the name of a DSS Server in the Cluster. All the servers in the cluster should use the same port number. The InitialPoolSize is for each server in the cluster. If the default values are used, this method will create four connections to each server initially.
Before the Web API can handle any request, a connection pool needs to be established. When a Web request comes in, the API gets a connection from the connection pool to serve the request. Connections in the connection pool are initially in free status. Once used to serve a Web request, they are in busy status. Once a request is completed (session ID returned for create session, messageID returned after executing a report for example), the connection is returned to the connection pool in free status.
When the API detects that the free connections in a connection pool is too low (less than two connections) and the connection pool has not reached the maximum pool size, it dynamically expands the connection pool. In the case when the connection pool reaches its maximum pool size, if a Web request comes in when all connections are busy, the request waits for a free connection. The time to wait is configurable through this admin interface. When the waiting time is up and there is still no free connections, a Server too busy error is returned. Through this admin interface, an administrator can monitor the status of the connection pool. When all the connections in the connection pool are always stay in busy status, that means a lot of the Web users receives Server too busy messages. This is when the administrator needs to either adjust the max-wait time out setting or increase the connection pool size.
The API also balances the load among cluster nodes. The load is currently measured as the number of logins to a server.
- Parameters:
nodeName
- The name of the cluster node(Intelligence Server name).port
- The port number that the Intelligence Server is listening on. [Default=0]initialPoolSize
- The initial size of the connection pool. [Default=4]maxPoolSize
- The maximum size of the connection pool. [Default=100]- Returns:
- A
WebClusterNode
object used to connect to the Server. - Throws:
WebObjectsException
- Signals an error condition while connecting to an Intelligence Server cluster.
-
disconnect
void disconnect(java.lang.String nodeName)
This method is used to disconnect from an Intelligence Server Cluster.This method will disconnect the API from a DSS Server Cluster. The nodeName is the name of a server in the cluster. The "busy" connections will not be disconnected and destroyed until they are returned to the "free" status. This means that this method will disconnect the connections gracefully. All ongoing requests will have a chance to be completed.
- Parameters:
nodeName
- The name of the Intelligence Server.
-
getCluster
WebCluster getCluster(java.lang.String nodeName) throws WebObjectsException
This method returns aWebCluster
interface for a given node name. The returnedWebCluster
interface is a collection of Cluster Nodes(Intelligence Servers) that the given cluster node belongs to.The cluster information returned by this method may not be the latest. To get the latest cluster membership or the load for each cluster node, you need to call RefreshCluster(nodeName) first.
- Parameters:
nodeName
- The name of an Intelligence Server that the API is currently connected to.- Returns:
- A collection of
WebClusterNode
. It will return a null object if the node was not found. - Throws:
WebObjectsException
- Signals an error condition while getting the cluster.
-
getClusterNode
WebClusterNode getClusterNode(java.lang.String nodeName) throws WebObjectsException
Returns anWebClusterNode
interface for a given node name. The returnedWebClusterNode
interface contains the properties of the cluster node. Through this interface, a user can get the node name, load, connection pool size, the number of busy connections and the number of free connections. The connection pool size can also be set through this interface.The load of the cluster node returned by this method may not be the latest. To get the latest load for this cluster node, you need to call RefreshCluster(NodeName) first.
- Parameters:
nodeName
- The name of the Intelligence Server. The API must be connected to this server.- Returns:
- The interface to the Intelligence Server. It will return null if the node was not found.
- Throws:
WebObjectsException
- Signals an error condition while getting the cluster node.
-
getClusters
WebClusters getClusters() throws WebObjectsException
This method returns a collection of Intelligence Server Clusters representing all clusters that the API is connected to.The cluster information returned by this method may not be the latest. To get the latest cluster membership or the load for each cluster node, you need to call RefreshCluster first.
- Returns:
- The cluster collection.
- Throws:
WebObjectsException
- Signals an error condition while getting the clusters.
-
getRequestTimeOutMillis
int getRequestTimeOutMillis()
Returns the number of milliseconds that the Web API will wait for a Server to respond to a request.- Returns:
- The timeout, in milliseconds, for requests to the Intelligence Server.
-
getServerBusyTimeOutMillis
int getServerBusyTimeOutMillis()
Returns the number of milliseconds that a request waits for a "free" connection before returning the "Server too busy" error message.- Returns:
- The timeout, in milliseconds, that the API will wait for a free connection.
-
setRequestTimeOutMillis
void setRequestTimeOutMillis(int newTimeoutMillis)
Sets the number of milliseconds that the Web API will wait for a Server to respond to a request.- Parameters:
newTimeoutMillis
- The timeout, in milliseconds, for requests to the Intelligence Server.
-
setInitConnectionPoolFailureTolerance
void setInitConnectionPoolFailureTolerance(int connectionFailureTolerance)
sets the number of times that the Web API could fail for initialize the connection pool.- Parameters:
connectionFailureTolerance
-
-
setServerBusyTimeOutMillis
void setServerBusyTimeOutMillis(int newTimeout)
Sets the number of milliseconds that a request waits for a "free" connection before returning the "Server too busy" error message.- Parameters:
newTimeout
- The new value for this timeout.
-
refreshCluster
void refreshCluster(java.lang.String nodeName) throws WebObjectsException
Refreshes the cluster information that the API returns. It only refreshes the cluster that the given node belongs to. This method should be called if you want to get the latest cluster membership information or the load for each cluster node.- Parameters:
nodeName
- The name of a node in the cluster to refresh.- Throws:
WebObjectsException
- Signals an error condition while refreshing the cluster.
-
refreshAllClusters
void refreshAllClusters() throws WebObjectsException
Refreshes all clusters that the Web API is connected to.- Throws:
WebObjectsException
- Signals an error condition while refreshing the cluster.
-
setEncryption
void setEncryption(boolean encryption)
Sets whether the API should use encryption when talking to the Intelligence Server. If set to true, we will configuresetEncryptionMode(EncryptionMode)
to useEncryptionMode.AES
. It is recommended to usesetEncryptionMode(EncryptionMode)
instead of this method.- Parameters:
encryption
- True if encryption should be used, false otherwise.
-
getEncryption
boolean getEncryption()
Returns whether the API is set to use encryption when talking to the Intelligence Server.- Returns:
- False if
getEncryptionMode()
returnsEncryptionMode.OFF
, otherwise true.
-
setEncryptionMode
void setEncryptionMode(EncryptionMode mode)
Sets whether the API should use encryption when talking to the Intelligence Server, and the nature of the encryption mode. Some encryption modes likeEncryptionMode.SSL
may require some additional configuration - also seeEncryptionModeConfigurationSSL
.
-
getEncryptionMode
EncryptionMode getEncryptionMode()
Returns the currentEncryptionMode
configured.
-
setAutoConnect
void setAutoConnect(boolean autoConnect)
Sets the autoConnect setting on the XMLAPI. By default, this is true; if it is false, then the XMLAPI will never connect to a server unless the connect method is called explicitly. This setting affects the whole web application - it does not have to be set on a per-server basis.- Parameters:
autoConnect
- The new value to use for the auto-reconnect setting.
-
getAutoConnect
boolean getAutoConnect()
Returns the current autoConnect setting on the XMLAPI. This setting is a global flag; it will affect all threads contacting the Intelligence Server.- Returns:
- The current autoConnect setting.
-
setKeepAlive
void setKeepAlive(boolean keepAlive)
Sets the keepAlive setting on the XMLAPI. By default, this is false. When keep alive on this interface is true, all connections between web server and Intelligence Servers will be kept alive. When keep alive on this interface is false, the keep alive property of a particular connection will be determined by the keep alive setting onWebClusterNode
interface.- Parameters:
keepAlive
- The new value to use for the keep alive setting.
-
getKeepAlive
boolean getKeepAlive()
Returns the keepAlive setting on the XMLAPI. By default, this is false. When keep alive on this interface is true, all connections between web server and Intelligence Servers will be kept alive. When keep alive on this interface is false, the keep alive property of a particular connection will be determined by the keep alive setting onWebClusterNode
interface.- Returns:
- The current keepAlive setting.
-
getClusterInfos
WebClusterInfos getClusterInfos() throws WebObjectsException
- Throws:
WebObjectsException
-
-