Package com.microstrategy.webapi

Interface IDSSXMLAdmin

  • public interface IDSSXMLAdmin
    IDSSXMLAdmin is an interface used for Web API administration purposes. Through this interface, 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

    • Field Detail

      • DEFAULT_Connect_port

        static final int DEFAULT_Connect_port
        Default value for the port parameter of the Connect method.
        See Also:
        Constant Field Values

      • UNSPECIFIED_Connect_port

        static final int UNSPECIFIED_Connect_port
        Unspecified value for the port means to not use the port when comparing cluster nodes.
        See Also:
        Constant Field Values

      • DEFAULT_IServer_Connect_port

        static final int DEFAULT_IServer_Connect_port
        See Also:
        Constant Field Values

      • DEFAULT_IServer_Connect_port_TLS

        static final int DEFAULT_IServer_Connect_port_TLS
        See Also:
        Constant Field Values

      • DEFAULT_Connect_initialPoolSize

        static final int DEFAULT_Connect_initialPoolSize
        Default value for the initialPoolSize parameter of the Connect method.
        See Also:
        Constant Field Values

      • DEFAULT_Connect_connectionPoolSize

        static final int DEFAULT_Connect_connectionPoolSize
        Default value for the connectionPoolSize parameter of the Connect method.
        See Also:
        Constant Field Values

    • Method Detail

      • Connect

        void Connect​(java.lang.String nodeName,
             int port,
             int initialPoolSize,
             int connectionPoolSize)
      throws MSTRWebAPIException
        Connects the Web API to an Intelligence Server cluster.

        A connection is a TCP/IP connection between a Web XML API and a DSS Server. It is used by the XML 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 and ConnectionPoolSize are for each server in the cluster. If the default values are used, this method will create four connections to each server initially. The default maximum connection pool size for both servers is 100.

        Before the Web XML API can handle any request, a connection pool needs to be established. When a Web request comes in, the XML 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 sesion, messageID returned after executing a report for example), the connection is returned to the connection pool in free status.

        When XML 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.

        TThe XML 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]
        connectionPoolSize - The maximum size of the connection pool. [Default=100]
        Throws:
        MSTRWebAPIException - Signals an error condition.

      • ConnectEx

        IDSSXMLClusterNode ConnectEx​(java.lang.String nodeName,
                             int port,
                             int initialPoolSize,
                             int connectionPoolSize)
                      throws MSTRWebAPIException
        Connects the Web API to an Intelligence Server cluster.

        A connection is a TCP/IP connection between a Web XML API and a DSS Server. It is used by the XML 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 and ConnectionPoolSize are for each server in the cluster. If the default values are used, this method will create four connections to each server initially. The default maximum connection pool size for both servers is 100.

        Before the Web XML API can handle any request, a connection pool needs to be established. When a Web request comes in, the XML 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 sesion, messageID returned after executing a report for example), the connection is returned to the connection pool in free status.

        When XML 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.

        TThe XML 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]
        connectionPoolSize - The maximum size of the connection pool. [Default=100]
        Returns:
        IDSSXMLClusterNode that represents the nodeName just connected
        Throws:
        MSTRWebAPIException - Signals an error condition.

      • Disconnect

        @Deprecated
void Disconnect​(java.lang.String nodeName)
        Deprecated.
        This method is used to disconnect from an Intelligence Server Cluster.

        This method will disconnect the XML 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.

      • Disconnect

        void Disconnect​(java.lang.String nodeName,
                int port)
        This method is used to disconnect from an Intelligence Server Cluster.

        This method will disconnect the XML 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.

      • FindClusterNodeByCanonicalName

        @Deprecated
java.util.Optional<IDSSXMLClusterNode> FindClusterNodeByCanonicalName​(java.lang.String canonicalName)
                                                               throws MSTRWebAPIException
        Deprecated.
        Finds IDSSXMLClusterNode by matching canonical name in both active and inactive nodes tracked by IDSSXMLAdmin. The canonicalName parameter must be the canonical name as gotten from IDSSXMLClusterNode.getCanonicalName(). If it is anything else (like an ip address) this method will fail by returning an empty IDSSXMLClusterNode

        This method involves no complicated name/address resolution logic.

        Deprecated. Please use FindClusterNodeByCanonicalName that includes the port. THIS METHOD IS NOT SUPPORTED FOR USE IN CUSTOM APPLICATION DEVELOPMENT. THE METHOD IS SUBJECT TO CHANGE IN FUTURE RELEASES AND SOME METHODS AND PROPERTIES MAY NOT BE SUITABLE FOR CUSTOM DEVELOPMENT.
        Parameters:
        canonicalName - Name as in IDSSXMLClusterNode.getCanonicalName()
        Returns:
        The node
        Throws:
        MSTRWebAPIException - Signals an unexpected error condition.
        Since:
        MicroStrategy Web 11.2 GA

      • FindClusterNodeByCanonicalName

        java.util.Optional<IDSSXMLClusterNode> FindClusterNodeByCanonicalName​(java.lang.String canonicalName,
                                                                      int port)
                                                               throws MSTRWebAPIException
        Finds IDSSXMLClusterNode by matching canonical name in both active and inactive nodes tracked by IDSSXMLAdmin. The canonicalName parameter must be the canonical name as gotten from IDSSXMLClusterNode.getCanonicalName(). If it is anything else (like an ip address) this method will fail by returning an empty IDSSXMLClusterNode

        This method involves no complicated name/address resolution logic.

        THIS METHOD IS NOT SUPPORTED FOR USE IN CUSTOM APPLICATION DEVELOPMENT. THE METHOD IS SUBJECT TO CHANGE IN FUTURE RELEASES AND SOME METHODS AND PROPERTIES MAY NOT BE SUITABLE FOR CUSTOM DEVELOPMENT.
        Parameters:
        canonicalName - Name as in IDSSXMLClusterNode.getCanonicalName()
        Returns:
        The node
        Throws:
        MSTRWebAPIException - Signals an unexpected error condition.
        Since:
        MicroStrategy Web 11.2 GA

      • GetCluster

        IDSSXMLCluster GetCluster​(java.lang.String nodeName,
                          int port)
                   throws MSTRWebAPIException
        This method returns an IDSSXMLCluster interface for a given node name. The returned IDSSXMLCluster 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.
        port - The port of an Intelligence Server that the API is currently connected to.
        Returns:
        An IDSSXMLClusterNode object.
        Throws:
        MSTRWebAPIException - Signals an error condition.

      • GetCluster

        @Deprecated
IDSSXMLCluster GetCluster​(java.lang.String nodeName)
                   throws MSTRWebAPIException
        Deprecated.
        This method returns an IDSSXMLCluster interface for a given node name. The returned IDSSXMLCluster 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 IDSSXMLClusterNode.
        Throws:
        MSTRWebAPIException - Signals an error condition.

      • GetClusterNode

        @Deprecated
IDSSXMLClusterNode GetClusterNode​(java.lang.String nodeName)
                           throws MSTRWebAPIException
        Deprecated.
        Returns an IDSSXMLClusterNode interface for a given node name. The returned IDSSXMLClusterNode 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. Guaranteed to not be null
        Throws:
        MSTRWebAPIException - Signals an error condition. An exception is raised if node is not connected.

      • GetClusterNode

        IDSSXMLClusterNode GetClusterNode​(java.lang.String nodeName,
                                  int port)
                           throws MSTRWebAPIException
        Returns an IDSSXMLClusterNode interface for a given node name. The returned IDSSXMLClusterNode 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. Guaranteed to not be null
        Throws:
        MSTRWebAPIException - Signals an error condition. An exception is raised if node is not connected.

      • GetClusters

        IDSSXMLClusters GetClusters()
        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.

      • 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.

      • putRequestTimeOutMillis

        void putRequestTimeOutMillis​(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.

      • putInitConnectionPoolFailureTolerance

        void putInitConnectionPoolFailureTolerance​(int tolerance)
        Sets the number of times that the Web API could fail when initializing the connection pool.
        Parameters:
        tolerance -

      • putServerBusyTimeOutMillis

        void putServerBusyTimeOutMillis​(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.

      • invalidateClusterMembershipCache

        void invalidateClusterMembershipCache​(java.lang.String iNodeName,
                                      int iPort)
        Forces the RefreshClusterMembership cache to be invalidated

      • RefreshCluster

        @Deprecated
void RefreshCluster​(java.lang.String nodeName)
             throws MSTRWebAPIException
        Deprecated.
        Refreshes the cluster information that the API returns. It takes an optional node name. If a node name is given, it only refreshes the cluster that the given node belongs to. If the node name is null or empty, it refreshes all clusters that the Web API is connected 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, or an empty string if all clusters should be refreshed.
        Throws:
        MSTRWebAPIException - Signals an error condition.

      • putEncryption

        @Deprecated
void putEncryption​(boolean encryption)
        Deprecated.
        use setEncryptionMode(EncryptionMode)
        Sets whether the API should use encryption when talking to the Intelligence Server. If this is not set, then only the user password will be encrypted - all other data will be plaintext to/from the Server.
        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:
        True if encryption will be used, false otherwise.

      • setAutoConnect

        void setAutoConnect​(boolean autoConnect)
        Sets the autoconnect setting of the XMLAPI. This setting will affect all objects and threads in this instance of the XMLAPI. If this is true, then calls such as CreateSession, GetProjects, and CheckVersion will automatically connect to an unconnected Intelligence Server. If this value is false, the only way to connect to a server is through an explicit Connect call. By default, this property is false.
        Parameters:
        autoConnect - The new value of the autoConnect parameter.

      • getAutoConnect

        boolean getAutoConnect()
        Returns the current autoconnect setting of the XMLAPI. This setting will affect all objects and threads in this instance of the XMLAPI. If this is true, then calls such as CreateSession, GetProjects, and CheckVersion will automatically connect to an unconnected Intelligence Server. If this value is false, the only way to connect to a server is through an explicit Connect call. By default, this property is false.
        Returns:
        The current autoConnect setting of the XMLAPI.

      • putKeepAlive

        void putKeepAlive​(boolean keepAlive)
        Sets Keep Alive parameter of the socket connections between web server and Intelligence Servers. On IDSSXMLClusterNode, it also has a setting of keep alive. 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 on IDSSXMLClusterNode interface.
        Parameters:
        keepAlive - The new value of the keep alive parameter.
        See Also:
        IDSSXMLClusterNode.setKeepAlive(boolean)

      • getKeepAlive

        boolean getKeepAlive()
        Returns Keep Alive parameter of the socket connections between web server and Intelligence Servers. On IDSSXMLClusterNode, it also has a setting of keep alive. 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 on IDSSXMLClusterNode interface.
        Returns:
        The value of keep alive parameter.
        See Also:
        IDSSXMLClusterNode.getKeepAlive()

      • setEncryptionMode

        EncryptionMode setEncryptionMode​(EncryptionMode mode)
        Configures the kind of encryption to use. Note that to use EncryptionMode.SSL it may also be necessary to setup #getSSLConfiguration() depending on the certicate configured on the Intelligence Server.
        Returns:
        previous mode

      • FindClusterNode

        IDSSXMLClusterNode FindClusterNode​(java.lang.String nodeName,
                                   int port,
                                   boolean includeInactive)
                            throws MSTRWebAPIException
        FindClusterNode returns the cluster node as known by the system. If the cluster node is not known this method returns null. The includeInactive parameter, if false will only find the node if it is active. If true, it will search both active and inactive
        This method is somewhat of a specialty. You should almost always use FindClusterNode with just the nodeName and port. That is equivalent to using this method where includeInactive=true.
        Throws:
        MSTRWebAPIException
        See Also:
        GetClusterNode(String)

      • getIServerPlatform

        int getIServerPlatform​(java.lang.String sessionID)
                throws MSTRWebAPIException
        Returns the platform of Intelligence Server.
        Returns:
        EnumDSSXMLLDAPPlatform.DssXmlLDAPPlatformWindows or DssXmlLDAPPlatformForLinux
        Throws:
        MSTRWebAPIException - thrown if an error occurs during retrieval

      • checkConnection

        boolean checkConnection​(java.lang.String serverName,
                        int serverPort)
                 throws MSTRWebAPIException
        checkConnection checks to see if the cluster node corresponding to the input serverName and serverPort exists in a cluster and is connected to the Intelligence Server.

        If the cluster node does not exist, an attempt to connect will be made if getAutoConnect() is true.

        checkConnection returns true if the cluster node is connected, otherwise it returns false. An exception is thrown if the connection cannot be established.

        Parameters:
        serverName - name of the Intelligence Server.
        serverPort - port of the Intelligence Server.
        Returns:
        true if the cluster node is connected to the Intelligence Server.
        Throws:
        MSTRWebAPIException - if there was a problem establishing a connection.