com.ibm.websphere.management.configservice

Interface ConfigService

  • All Known Implementing Classes:
    ConfigServiceProxy

    public interface ConfigService
    This is the public interface of configure service component, it is also the interface of ConfigService MBean. Config service component provides programmatic capability to query or modify configuration data locally or remotely, and manages the location and the content of configuration documents on behalf of user.

    Class javax.management.ObjectName is used to uniquely identify any configuration data. However configuration data are not registered in the JMX server as MBeans since configuration data only represent the configuration information of managed objects and not the actual runtime attributes of managed objects, . In another word, you can not use AdminServcie.queryNames method to query config data.

    The keys that can be used in the ObjectName are listed as below :

    Class javax.management.AttributeList is used to represent the name and value of config data properties. Any attribute list returned from ConfigService interface contains following system attributes:

    • SystemAttributes._WEBSPHERE_CONFIG_DATA_ID
    • SystemAttributes._WEBSPHERE_CONFIG_DATA_TYPE

    There are three types of attribute: primitive type attribute, nested config data attribute and reference attribute. A primitive type attribute represents a property of a config data, a nested config data attribute represents a nested config data contained by its parent config data, and a reference config data attribute represents associations between config data. The value of nested config data attribute is represented in a format of attribute list. Nested config data can be accessed directly as an independent config data. The value of reference attribute is represented by the ObjectName of the referred config data.

    Config service component also provides getRelationship and getRelationships methods to traverse configuration topology tree. For instances, get the list of servers on a specified node, or get the list of resources installed on a specified node etc.

    Three methods are provided to query meta data information regarding to supported config data types, their attributes and relationships: getSupportedConfigObjectTypes, getAttributesMetaInfo and getRelationshipsMetaInfo.

    Config service component supports session concept. User may start a session, do bunch of operations, then save all the changes made during the seesion into config repository at one time. If any of the configuration operations failed in the middle , user can throw away changes made so far by calling discard method. When user is done with the session, user must call the discard method explicitly to recycle the resources used by the session. Example code below shows how to use the session typically. 

            Session seesion = new Session();
        configService.getAttributes(session, .....);
        configService.setAttributes(session, .....);
        configService.createConfigData(session, ....);
        configService.deleteConfigData(sesssion, ...);
                      :
                      :
                      :
        save(session);

        or
        discard(session);
        configService.getAttributes(session, .....);
        configService.setAttributes(session, .....);
        configService.createConfigData(session, ....);
        configService.deleteConfigData(sesssion, ...);
                      :
                      :
                      :
        save(session, overwriteOnConflict);

        discard(session);

    Updates made through different sessions are isolated and serialized.If multiple users update same document at same time through different sessions, conflict will be detected. Users can query the list of conflicted documents by calling getConflictDocuments method. Then user can choose if they want to discard the change or save the change by overwriting other user's update on the same document through the save method.

    If session is null, then the operation will be executed in a separate anoynmous session, i.e. the operation creates a new session, does the work and saves the session in one method call. However session creation is not cheap, so it is recommended that user creates session and reuses the session whenever it is possible.

    When security is enabled all the operations defined in this interface are protected by WebSphere administrative security. See WebSphere info center for more detailed documentation regarding to how the WebSphere administrative security works.

    • Method Summary

      Methods 
      Modifier and Type Method and Description
      void addElement(Session session, javax.management.ObjectName configData, java.lang.String attribute, java.lang.Object element, int position)
      Add an element into a collection type attribute of a config data.
      void clearServerPortCache(Session session)
      Clear the cache in the session used for a server port resolution
      javax.management.ObjectName createConfigData(Session session, javax.management.ObjectName parent, java.lang.String attributeName, java.lang.String type, javax.management.AttributeList attrList)
      create a Config Data.
      javax.management.ObjectName createConfigDataByTemplate(Session session, javax.management.ObjectName parent, java.lang.String attributeName, javax.management.AttributeList attrList, javax.management.ObjectName template)
      Create a config data based on specified template.
      void deleteConfigData(Session session, javax.management.ObjectName configData)
      Delete the specified config data and its children.
      void discard(Session session)
      Discard changes made in the session since the last save or discard call.
      java.lang.Object getAttribute(Session session, javax.management.ObjectName configData, java.lang.String attribute)
      Get the attribute value of the specified config data.
      java.lang.Object getAttribute(Session session, javax.management.ObjectName configData, java.lang.String attribute, boolean recursive)
      Get the attribute value of the specified config data.
      javax.management.AttributeList getAttributes(Session session, javax.management.ObjectName configData, java.lang.String[] attributes, boolean recursive)
      Get the attribute values of the config data.
      javax.management.AttributeList getAttributesMetaInfo(java.lang.String configDataType)
      Get the meta information about the attributes of specified config data type.
      java.util.Map getConflictDocuments(Session session)
      Get the list of documents that have conflict updates made by other sessions.
      javax.management.ObjectName[] getRelationship(Session session, javax.management.ObjectName configData, java.lang.String relationship)
      Get the relationship value of the specified config object and relationship name.
      javax.management.AttributeList getRelationships(Session session, javax.management.ObjectName configData, java.lang.String[] relationshipNames)
      Get the named relationship values of specified config object.
      javax.management.AttributeList getRelationshipsMetaInfo(java.lang.String configObjectType)
      Get the meta information about the relationships of specified config data type, such as the type of the relationship value, the multiplicity of the relationship value etc.
      java.lang.String[] getSupportedConfigObjectTypes()
      Returns the list of supported Config object types.
      java.lang.String[] getUnsavedChanges(Session session)
      Get all the documents that changed in the session after last save or discard call.
      javax.management.ObjectName[] queryConfigObjects(Session session, javax.management.ObjectName scope, javax.management.ObjectName pattern, javax.management.QueryExp query)
      The query method for config data in the config repository.
      javax.management.ObjectName[] queryConfigObjectsAtCurrentScope(Session session, javax.management.ObjectName scope, java.lang.String type)
      The query method for config data in the config repository
      javax.management.ObjectName[] queryTemplates(Session session, java.lang.String type)
      The query method for templates.
      void removeElement(Session session, javax.management.ObjectName configData, java.lang.String attribute, java.lang.Object element)
      Remove an element from collection type attribute of a config data.
      void resetAttributes(Session session, javax.management.ObjectName configData, javax.management.AttributeList attrList)
      Reset the attributes for the config data.
      javax.management.ObjectName[] resolve(Session session, javax.management.ObjectName scope, java.lang.String containmentPath)
      Resolve the config object based on the specified containment path.
      javax.management.ObjectName[] resolve(Session session, java.lang.String containmentPath)
      Resolve the config object based on the specified containment path.
      void save(Session session, boolean overwriteOnConflict)
      Save the changes made in the session to config repository.
      void setAttributes(Session session, javax.management.ObjectName configData, javax.management.AttributeList attrList)
      Modify attributes of the specified config data.
      void setProperties(Session session, java.util.HashMap props)
      Set properties that associates with the specified session.
      void unsetAttributes(Session session, javax.management.ObjectName configData, java.lang.String[] attributes)
      Clear the specified attributes from the config data.
      ValidationResult validate(Session session, javax.management.ObjectName scope)
      Validate the configuration within the specified scope.

    • Method Detail

      • getConflictDocuments

        java.util.Map getConflictDocuments(Session session)
                                   throws ConfigServiceException,
                                          ConnectorException
        Get the list of documents that have conflict updates made by other sessions.
        Parameters:
        session - the session id.
        Returns:
        a map of conflicted document updates. key is the document uri, and value is one of the integer defined as below:
        • 1 - document is modified by other session.
        • 2 - document is removed by other session.
        • 3 - document is added by other session.
        Throws:
        ConfigServiceException
        ConnectorException

      • getRelationshipsMetaInfo

        javax.management.AttributeList getRelationshipsMetaInfo(java.lang.String configObjectType)
                                                        throws ConfigServiceException,
                                                               ConnectorException
        Get the meta information about the relationships of specified config data type, such as the type of the relationship value, the multiplicity of the relationship value etc.
        Parameters:
        configObjectType - config ojbect type. It must be one of the types returned from getSupportedConfigObjectTypes method.
        Returns:
        the relationship information in a format of AttributeList. The attribute name is the relationship name and the attribute value is the detailed information regarding to this relationship in a form of AttributeList. Here are list of attributes in the relationship meta info:
        • SystemAttributes._ATTRIBUTE_METAINFO_NAME
        • SystemAttributes._ATTRIBUTE_METAINFO_TYPE
        • SystemAttributes._ATTRIBUTE_METAINFO_IS_COLLECTION
        Throws:
        ConfigServiceException
        ConnectorException

      • getAttributesMetaInfo

        javax.management.AttributeList getAttributesMetaInfo(java.lang.String configDataType)
                                                     throws ConfigServiceException,
                                                            ConnectorException
        Get the meta information about the attributes of specified config data type. Follwing are list of attributes encoded in the returned meta info attribute list.
        • SystemAttributes._ATTRIBUTE_METAINFO_NAME
        • SystemAttributes._ATTRIBUTE_METAINFO_TYPE
        • SystemAttributes._ATTRIBUTE_METAINFO_IS_COLLECTION
        • SystemAttributes._ATTRIBUTE_METAINFO_IS_REQUIRED
        • SystemAttributes._ATTRIBUTE_METAINFO_DEFAULT_VALUE
        • SystemAttributes._ATTRIBUTE_METAINFO_ENUM_INFO
        • SystemAttributes._ATTRIBUTE_METAINFO_IS_OBJECT
        • SystemAttributes._ATTRIBUTE_METAINFO_IS_REFERENCE
        Parameters:
        configDataType - the type of the config data.
        Returns:
        the attribute information in a format of AttributeList. The attribute name is the attribute name and the attribute value is the detailed attribute meta information in a form of AttributeList.
        Throws:
        ConfigServiceException
        ConnectorException

      • queryConfigObjects

        javax.management.ObjectName[] queryConfigObjects(Session session,
                                               javax.management.ObjectName scope,
                                               javax.management.ObjectName pattern,
                                               javax.management.QueryExp query)
                                                 throws ConfigServiceException,
                                                        ConnectorException
        The query method for config data in the config repository.
        Parameters:
        scope - the scope of query. It may be an ObjectName of a cell, node or server. Whole repository will be queried if scope is null.
        pattern - the object name pattern that identifies MBeans to be returned. SystemAttributes._WEBSPHERE_CONFIG_DATA_TYPE is required to minimize the scope of query. SystemAttributes._WEBSPHERE_CONFIG_DATA_TYPE must be one the supported config object types it presents
        query - The query expression to be applied for selecting config ojbects. If null is specified, no query expression will be applied for selecting config objects. Current implementation only supports null input.
        Returns:
        ObjecNames of config data that match the specified query criteria. Returns an empty array if no matching config data are found.
        Throws:
        ConfigServiceException
        ConnectorException

      • queryConfigObjectsAtCurrentScope

        javax.management.ObjectName[] queryConfigObjectsAtCurrentScope(Session session,
                                                             javax.management.ObjectName scope,
                                                             java.lang.String type)
                                                               throws ConfigServiceException,
                                                                      ConnectorException
        The query method for config data in the config repository
        Parameters:
        scope - the scope of query. It may be an ObjectName of a cell, node, server or cluster. It only queries the given scope
        type - the config object type. It must be one the supported config object type.
        query - The query expression to be applied for selecting config ojbects. If null is specified, no query expression will be applied for selecting config objects. Current implementation only supports null input.
        Returns:
        ObjecNames of config data that match the specified query criteria. Returns an empty array if no matching config data are found.
        Throws:
        ConfigServiceException
        ConnectorException

      • resolve

        javax.management.ObjectName[] resolve(Session session,
                                    java.lang.String containmentPath)
                                      throws ConfigServiceException,
                                             ConnectorException
        Resolve the config object based on the specified containment path.
        Parameters:
        session - the seesion id.
        containmentPath - the containment path of config data. The format this arguemnt is type=name:type=name:... For example, Node=node1:Server=process1:Application=myAppServer. The type is the config data type, name if the config data name. The name field is optional. If name is not specified, then only type is matched. The name field may be double quoted. If the name field is not quoted, then the space around of value field will be trimed.
        Returns:
        an array of matched config data.
        Throws:
        ConfigServiceException
        ConnectorException

      • resolve

        javax.management.ObjectName[] resolve(Session session,
                                    javax.management.ObjectName scope,
                                    java.lang.String containmentPath)
                                      throws ConfigServiceException,
                                             ConnectorException
        Resolve the config object based on the specified containment path.
        Parameters:
        session - the seesion id.
        scope - the scope of resolve. It may be an ObjectName of a cell, node or server. Whole repository will be queried if scope is null
        containmentPath - the containment path of config data. The format this arguemnt is type=name:type=name:... For example, Node=node1:Server=process1:Application=myAppServer. The type is the config data type, name if the config data name. The name field is optional. If name is not specified, then only type is matched. The name field may be double quoted. If the name field is not quoted, then the space around of value field will be trimed.
        Returns:
        an array of matched config data.
        Throws:
        ConfigServiceException
        ConnectorException

      • validate

        ValidationResult validate(Session session,
                        javax.management.ObjectName scope)
                          throws ConfigServiceException,
                                 ConnectorException
        Validate the configuration within the specified scope.
        Parameters:
        session - session id.
        scope - the scope of validation. Scope can be the ObjectName of a cell, node or server. if null is specified, then whole repository will be validated. If any other type object is specified, use its nearest ancestor that can be a valid scope.
        Returns:
        the validation result.
        Throws:
        ConfigServiceException
        ConnectorException

      • createConfigData

        javax.management.ObjectName createConfigData(Session session,
                                           javax.management.ObjectName parent,
                                           java.lang.String attributeName,
                                           java.lang.String type,
                                           javax.management.AttributeList attrList)
                                             throws ConfigServiceException,
                                                    ConnectorException
        create a Config Data. If the attribute is a collection type attribute, this method will create the object and add the newly created object at the end of list.
        Parameters:
        session - the seesion id.
        parent - the id of the parent config data.
        attributeName - the name of the relationship or attribute between the parent and child config data.
        type - the type of created config data. The type can be the type of the attribute specified in the attribute meta info, it can also be one of the subtypes listed in the attribute _ATTRIBUTE_METAINFO_SUBTYPES in the meta info of the attribute.
        attrList - the AttributeList of created config object.
        Returns:
        the config data id of created config object or config data.
        Throws:
        ConfigServiceException
        ConnectorException

      • createConfigDataByTemplate

        javax.management.ObjectName createConfigDataByTemplate(Session session,
                                                     javax.management.ObjectName parent,
                                                     java.lang.String attributeName,
                                                     javax.management.AttributeList attrList,
                                                     javax.management.ObjectName template)
                                                       throws ConfigServiceException,
                                                              ConnectorException
        Create a config data based on specified template. If the attribute is a collection type attribute, this method will create the object and add the created object at the end of list. Note unlike the createConfigData method, we don't allow user specify type in this method as the type of template will be the type of created object.
        Parameters:
        session - the seesion id.
        parent - the ObjectName of the parent config data.
        attributeName - - the name of the relationship or attribute name between the parent and child config data.
        attrList - - the AttributeList of created config object.
        template - - the template to be used during creation. Use system default template if null is supplied. The template can be one of the template returned from queryTemplates call, but it can be a config object or data in the repository.
        Returns:
        the config data id of created config data.
        Throws:
        ConfigServiceException
        ConnectorException

      • setAttributes

        void setAttributes(Session session,
                 javax.management.ObjectName configData,
                 javax.management.AttributeList attrList)
                   throws ConfigServiceException,
                          ConnectorException
        Modify attributes of the specified config data. Note this method does not change the attributes that are not specified in the attribute list.

        Parameters:
        session - the seesion id.
        configData - - the ObjectName of the config data.
        attrList - - the AttributeList that contains the list of attributes to be modified.
        Throws:
        ConfigServiceException
        ConnectorException

      • addElement

        void addElement(Session session,
              javax.management.ObjectName configData,
              java.lang.String attribute,
              java.lang.Object element,
              int position)
                throws ConfigServiceException,
                       ConnectorException
        Add an element into a collection type attribute of a config data.
        Parameters:
        session - the seesion id.
        configData - the ObjectName of the config data.
        attribute - the name of the attribute.
        element - the value of the element. It might be a primary data type, an attribute list or a object reference.
        position - the position added in the list. Element will be appended at the end if -1.
        Throws:
        ConfigServiceException
        ConnectorException

      • removeElement

        void removeElement(Session session,
                 javax.management.ObjectName configData,
                 java.lang.String attribute,
                 java.lang.Object element)
                   throws ConfigServiceException,
                          ConnectorException
        Remove an element from collection type attribute of a config data.
        Parameters:
        session - the seesion id
        configData - the ObjectName of the config data.
        attribute - the name of the attribute.
        element - the ObjectName of the element. In case of primitive data type, it should be the element value itself.
        Throws:
        ConfigServiceException
        ConnectorException

      • resetAttributes

        void resetAttributes(Session session,
                   javax.management.ObjectName configData,
                   javax.management.AttributeList attrList)
                     throws ConfigServiceException,
                            ConnectorException
        Reset the attributes for the config data. This method is basically do the same thing as the setAttributes call except that this method clears all the attributes value before call the setAttributes method.
        Parameters:
        session - the seesion id.
        configData - the ObjectName of the config object.
        attrList - the value of attribute list.
        Throws:
        ConfigServiceException
        ConnectorException

      • getAttributes

        javax.management.AttributeList getAttributes(Session session,
                                           javax.management.ObjectName configData,
                                           java.lang.String[] attributes,
                                           boolean recursive)
                                             throws ConfigServiceException,
                                                    ConnectorException
        Get the attribute values of the config data.
        Parameters:
        session - the seesion id.
        configData - ObjectName of config data.
        attributes - an array of attribute names whose value should be returned. null means all the attributes.
        recursive - returns a nested attribute list as the value of nested config data attribute if set to be true; return the ObjectName of nested config data as the value of nested config data attribute if set to be false.
        Returns:
        the attribute values of specified attributes in a form of AttributeList.
        Throws:
        ConfigServiceException
        ConnectorException

      • getAttribute

        java.lang.Object getAttribute(Session session,
                            javax.management.ObjectName configData,
                            java.lang.String attribute)
                              throws ConfigServiceException,
                                     ConnectorException
        Get the attribute value of the specified config data.
        Parameters:
        session - the seesion id.
        configData - the ObjectName of the config data.
        attribute - an attribute name.
        Returns:
        the attribute values of specified attribute.
        Throws:
        ConfigServiceException
        ConnectorException

      • getAttribute

        java.lang.Object getAttribute(Session session,
                            javax.management.ObjectName configData,
                            java.lang.String attribute,
                            boolean recursive)
                              throws ConfigServiceException,
                                     ConnectorException
        Get the attribute value of the specified config data.
        Parameters:
        session - the seesion id.
        configData - the ObjectName of the config data.
        attribute - an attribute name.
        recursive - returns a attribute values as the value of nested config data attribute if set to be true; return the Object of config data if set to be false.
        Returns:
        the attribute values of specified attribute.
        Throws:
        ConfigServiceException
        ConnectorException

      • getRelationship

        javax.management.ObjectName[] getRelationship(Session session,
                                            javax.management.ObjectName configData,
                                            java.lang.String relationship)
                                              throws ConfigServiceException,
                                                     ConnectorException
        Get the relationship value of the specified config object and relationship name.
        Parameters:
        session - the seesion id.
        configData - ObjectName of the config data.
        relationship - the name of the relationship.
        Returns:
        the value of the specified relationship on the object. The value of the relationship is represented as an array of ObjectName.
        Throws:
        ConfigServiceException
        ConnectorException

      • getRelationships

        javax.management.AttributeList getRelationships(Session session,
                                              javax.management.ObjectName configData,
                                              java.lang.String[] relationshipNames)
                                                throws ConfigServiceException,
                                                       ConnectorException
        Get the named relationship values of specified config object.

        This method skips invalid relationship name instead of throwing exception like getAttributes.

        Parameters:
        session - the seesion id.
        configData - ObjectName of the config data.
        relationshipNames - an array of the relationship names.
        Returns:
        the value of the specified relationship on the object as an AttributeList. The name of the Attribute is a relationship name and the value of the the Attribute is the value of the relationship which is represented in a form of ObjectName.
        Throws:
        ConfigServiceException
        ConnectorException
IBM WebSphere Application ServerTM
Release 8.5
  • Summary: 
  • Nested | 
  • Field | 
  • Constr | 
  • Method
  • Detail: 
  • Field | 
  • Constr | 
  • Method