com.bea.wli.sb.management.configuration
Interface ALSBConfigurationMBean

All Superinterfaces:

weblogic.management.provider.Service

public interface ALSBConfigurationMBean
extends weblogic.management.mbeanservers.Service

Provides various API to query, export and import resources, obtain validation errors, get and set environment values, and in general manage resources in an ALSB domain.

MBean instances:

There is a separate instance of ALSBConfigurationMBean for each session. There is also one more ALSBConfigurationMBean instance which works on the core data, i.e., the data which ALSB runtime uses. An ALSBConfigurationMBean instance is created whenever a new session is created via the SessionManagementMBean.createSession(String) API. This mbean instance is then used to perform configuration operations in that session. The mbean instance is destroyed when the corresponding session is activated or discarded.

More information about Sessions can be found in javadoc for SessionManagementMBean

Read vs. Write Operations:

Read operations are allowed on all sessions and on the core data via the corresponding MBean instance. Write operations, however, are only limited to sessions.

Creating, discarding or activating session

See documentation for SessionManagementMBean.

Obtaining and using ALSBConfigurationMBean

See documentation for SessionManagementMBean.

Importing and exporting configuration

The following code sample shows how to import and export configuration data.

 /**
 // Imports a configuration jar file, replaces environment values, activates it, and exports
 // the resource again.
 // @throws Exception
 /
static private void simpleImportExport(String importFileName, String passphrase) throws Exception {

 SessionManagementMBean sm = ... // obtain the mbean to create a session;

 // obtain the raw bytes that make up the configuration jar file
 File importFile = new File(importFileName);
 byte[] bytes = readBytes(importFile);


 // create a session
 String sessionName = "session." + System.currentTimeMillis();
 sm.createSession(sessionName);

 // obtain the ALSBConfigurationMBean that operates on the
 // session that has just been created
 ALSBConfigurationMBean alsbSession = getConfigMBean(sessionName);

 // import configuration into the session. First we upload the
 // jar file, which will stage it temporarily.
 alsbSession.uploadJarFile(bytes);

 // then we import the jar file
 ImportResult result =
     alsbSession.importUploaded(
         null,  // import everything in the jar file
         true,  // whether to include dependencies. This could be false
                // since we are importing everything in the jar file.
         false, // import as is, potentially overwriting the existing
                // environment values that may have been previously
                // customized. We will customize them explicitly below
         passphrase // non-null if configuration jar file contains
                    // sensitive information that has been encrypted
     );


 // print out status
 if (result.getImported().size() > 0) {
     System.out.println("The following resources have been successfully imported.");
     for (Ref ref : result.getImported()) {
         System.out.println("\t" + ref);
     }
 }

 if (result.getFailed().size() > 0) {
     System.out.println("The following resources have failed to be imported.");
     for (Map.Entry e : result.getFailed().entrySet()) {
         Ref ref = e.getKey();
         // Diagnostics object contains validation errors
         // that caused the failure to import this resource
         Diagnostics d = e.getValue();
         System.out.println("\t" + ref + ". reason: " + d);
     }

     // discard the changes to the session and exit
     System.out.println("Discarding the session.");
     sm.discardSession(sessionName);
     System.exit(1);
 }

 // peform changes on the imported data as needed. Usually
 // environment values need to be changed if configuration
 // is being moved from testing to production, or between
 // different domains.

 ...

 // activate the session
 sm.activateSession(sessionName, "description");

 // export information from the core data
 ALSBConfigurationMBean alsbcore = getConfigMBean(null);
 byte[] contents = alsbcore.export(Collections.singleton(Ref.DEFAULT_PROJECT_REF),
                                          // export everything under the default project
                                   true,  // also export any other resources that
                                          // resources in default project may depend on
                                   null); // do not encrypt sensitive information

 // the byte contents can be saved as jar file
}

 

Changing environment values

The following code shows two ways of changing environment values. Environment values can be changed either via the find-and-replace feature, or individually. While the former is more convenient the latter provides more control.

 // change environment values that differ between domains.
 // we simply change the string "localhost" to "productionhost"
 // in all the URIs

 EnvValueQuery evquery =
     new EnvValueQuery(
         null,        // search across all resource types
         Collections.singleton(EnvValueTypes.URI_ENV_VALUE_TYPE), // search only the URIs
         null,        // search across all projects and folders.
         true,        // only search across resources that are
                      // actually modified/imported in this session
         "localhost", // the string we want to replace
         false        // not a complete match of URI. any URI
                      // that has "localhost" as substring will match
         );

 int count = alsbSession.replaceEnvValues(evquery, "productionhost");
 System.out.println(count + " instances have been replaced.");

 // perform an even finer grained environment value replacement.
 // replace all file paths/URLs that start with "file:///c:/" and
 // replace with "file:///c:/{project/folder of the resource},
 // essentially making the file structure conform to the project
 // structure

 // find all env values in all resources that have been modified in
 // the session
 evquery = new EnvValueQuery(null, null, null, true, null, false);
 ArrayList envValuesToChange = new ArrayList();
 String prefix = "file:///c:/";

 for (QualifiedEnvValue qev : alsbSession.findEnvValues(evquery)) {
     if (qev.getValue() instanceof String && qev.getValue().toString().startsWith(prefix)) {
         Ref ref = qev.getOwner();
         String oldValue = (String) qev.getValue();
         String newValue = oldValue.substring(0, prefix.length()) +
             ref.getFullName() + // insert "/" separated path for the resource
             "/" + oldValue.substring(prefix.length());

         QualifiedEnvValue newEnvValue =
             new QualifiedEnvValue(qev.getOwner(),
                                   qev.getEnvValueType(),
                                   qev.getLocation(),
                                   newValue);

         envValuesToChange.add(newEnvValue);
         System.out.println("Env value " + qev.getOwner() + " : " + qev.getEnvValueType() +
                            " : " + qev.getLocation() + " : " + qev.getValue() +
                            " will be changed to " + newValue);
     }
 }

 // now directly set the env values
 alsbSession.assignEnvValues(envValuesToChange);
 

Querying resources

This mbean also allows querying resources based on certain criteria. The queries can be performed over the core (activated) data, or in a session, in which case the session view of the configuration will be used to return the query result. The following code shows a simple query that returns all WSDL based "https" services.

 ALSBConfigurationMBean alsbCore = getConfigMBean(null);
 ProxyServiceQuery query = new ProxyServiceQuery();

 // find all proxy services using https transport and WSDL based
 query.setTransportScheme("https");
 query.setWSDLBasedService(true);

 Set refs = alsbCore.getRefs(query);
 System.out.println("Resources that satisfy the search criteria are:");
 for (Ref ref : refs) {
     System.out.println(ref);
 }

 

Field Summary

static String	NAME
static String	TYPE

Method Summary

void	assignEnvValues(Collection<QualifiedEnvValue> envValues) Sets one or more environment value directly.
byte[]	export(Collection<Ref> refsToExport, boolean includeDependencies, String passphrase) Exports the given collection of references and returns bytes that make up the export data.
Collection<QualifiedEnvValue>	findEnvValues(EnvValueQuery query) Searches environment specific values based on the given query
Map<Ref,Diagnostics>	getDiagnostics(Collection<Ref> refs) Obtains diagnostic information about the given resources.
Set<Ref>	getRefs(Ref root) Returns all the resources, folders or projects that are under the given root.
Set<Ref>	getRefs(ResourceQuery query) Searches a particular resource type based on the given resource query and returns references to resources that satisfy the given criteria.
String	getSession() Returns the name of the session that this mbean operates on
ImportResult	importUploaded(Collection<Ref> refs, boolean includeDependencies, boolean preserveExistingEnvValues, String passphrase) Imports selected resources/projects/folders from the previously uploaded jar file into the session.
int	replaceEnvValues(EnvValueQuery query, String replacement) Find environment values as indicated by the query and replace all occurences of the env value pattern (as returned by EnvValueQuery.getSearchString() ) with the given parameter.
Set<Ref>	uploadJarFile(byte[] data) Obtains configuration data from a configuration jar file and locally (temporarily) stages it on the server.

Methods inherited from interface weblogic.management.mbeanservers.Service

getName, getParentAttribute, getParentService, getPath, getType

Field Detail

NAME

static final String NAME

See Also:

Constant Field Values

TYPE

static final String TYPE

Method Detail

getSession

String getSession()

Returns the name of the session that this mbean operates on

Returns:

the name of the session that this mbean operates on

getRefs

Set<Ref> getRefs(ResourceQuery query)
                 throws Exception

Searches a particular resource type based on the given resource query and returns references to resources that satisfy the given criteria.

Parameters:

query - the query

Returns:

a set of references to resources that satisfy the criteria

Throws:

Exception

getRefs

Set<Ref> getRefs(Ref root)
                 throws NotFoundException

Returns all the resources, folders or projects that are under the given root. The root can be a Domain (e.g., Ref.DOMAIN), a project or a folder. The result does not contain the given root argument.

Throws:

NotFoundException - if the given root is not found

IllegalArgumentException - if the root is null, or is a resource reference.

getDiagnostics

Map<Ref,Diagnostics> getDiagnostics(Collection<Ref> refs)
                                    throws Exception

Obtains diagnostic information about the given resources.

Parameters:

refs - the resource references for which to return the diagnostics. A null refs value returns all available diagnostics.

Returns:

Returns a mapping from resource references to diagnostics for these resources. The result contains mappings for only those references given in the argument that have a diagnostic object. If a resource does not have any diagnostics associated with it, the map does not contain an entry for this resource.

Throws:

Exception

export

byte[] export(Collection<Ref> refsToExport,
              boolean includeDependencies,
              String passphrase)
              throws Exception

Exports the given collection of references and returns bytes that make up the export data.

Parameters:

refsToExport - array of references to items to be exported. A reference to a resource causes that resource to be exported. If there is a reference to a folder, project, or the domain (via Ref.DOMAIN) then all resources under these are exported as well. In order to export all the resources simply call this method with Ref.DOMAIN.

includeDependencies - whether to include dependencies of the resources that are given in the refsToExport parameter

passphrase - the passphrase to use if encryption will be done

Returns:

bytes that make up an exported configuration in the form of a zip file. The result can be saved as a zip file and inspected with relevant tools.

Throws:

Exception

uploadJarFile

Set<Ref> uploadJarFile(byte[] data)
                       throws Exception

Obtains configuration data from a configuration jar file and locally (temporarily) stages it on the server. The import is finished by invoking the importUploaded(java.util.Collection, boolean, boolean, java.lang.String) method.

Parameters:

data - contents of a previously exported configuration jar file.

Returns:

set of references to resources found in the jar file

Throws:

Exception

importUploaded

ImportResult importUploaded(Collection<Ref> refs,
                            boolean includeDependencies,
                            boolean preserveExistingEnvValues,
                            String passphrase)
                            throws Exception

Imports selected resources/projects/folders from the previously uploaded jar file into the session. Once the import finishes (successfully or not) the staged config information is removed. The import continues even if some resources fail to import, and does not result in an exception. The failed imports are reported in the result.

Parameters:

refs - references to the resources/folders/projects to be imported. An entity can be listed multiple times (directly or indirectly via its parent folder/project). A reference to project, folder will cause all resources in the configuration jar file under that location to be imported. If null or Ref.DOMAIN all resources in the config jar are imported.

includeDependencies - whether to include dependencies of the resources that are given in the refs parameter which are also in uploaded jar file.

preserveExistingEnvValues - This flag controls whether certain environment values inside of a resource will be overwritten or preserved during an import. The import always overwrites any existing data, except environment values that are found in both the existing data and imported data. If this argument is true, the import of a resource (which already exists) proceeds as follows:

• If an env value is in the existing data, but not in the imported data, then the env value is removed.
• If an env value is in the imported data, but not in the existing data, it is added
• If an env value is in both existing data, and imported data, the imported env value replaces the existing env value.

passphrase - the pass phrase to use for decrypting resources that have been encrypted. Null value can be given if the jar file is known to not have been encrypted.

Returns:

ImportResult object that contains resources that are successfully imported, and those that have failed

Throws:

Exception

findEnvValues

Collection<QualifiedEnvValue> findEnvValues(EnvValueQuery query)

Searches environment specific values based on the given query

Parameters:

query - the search criteria for the environment values.

Returns:

collection of environment values that satisfy the given search criteria.

replaceEnvValues

int replaceEnvValues(EnvValueQuery query,
                     String replacement)
                     throws Exception

Find environment values as indicated by the query and replace all occurences of the env value pattern (as returned by EnvValueQuery.getSearchString() ) with the given parameter.

Parameters:

query - the query that indicates which env values to find

replacement - the replacement text. This text will be substituted for the env value pattern given in the query.

Returns:

the number of environment values that have been changed

Throws:

Exception

assignEnvValues

void assignEnvValues(Collection<QualifiedEnvValue> envValues)
                     throws NotFoundException,
                            UpdateException

Sets one or more environment value directly. This method is typically used after obtaining the existing environment values via the findEnvValues(com.bea.wli.config.env.EnvValueQuery) method to obtain the location of a particular environment value.

Parameters:

envValues - Environment values to set.

Throws:

NotFoundException - if a resource is not found

UpdateException - if any other exception occurs while updating the env values