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 OSB 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 OSB 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

Availability of ALSBConfigurationMBean during server startup

The initial registeration of ALSBConfigurationMBean instances for the core data and the existing sessions is performed after the server has started all the applications. More precisely, these mbeans are registered in the postStart method that is generated when loading the OSB kernel application. Any attempt to access the mbeans before this point will fail.

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.

Atomicity

All mbean methods are atomic. The operation will either succeed or will not have an effect.

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 using the new API.


 /**
 // Imports a configuration jar file, applies customization, activates it and exports the resources 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 get the default import plan and modify the plan if required
 ALSBJarInfo jarInfo = alsbSession.getImportJarInfo()
 ALSBImportPlan importPlan = jarInfo.getDefaultImportPlan();

 // Modify the plan if required and pass it to importUploaeded method
 ImportResult result = alsbSession.importUploaded(importPlan);

 // Pass null to importUploaded method to mean the default import plan.
 //ImportResult result = alsbSession.importUploaded(null);


 // 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 the customization to assign/replace environment values and
 // to modify the references.

 ...

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

 // export information from the core data
 ALSBConfigurationMBean alsbcore = getConfigMBean(null);
 //export the information at project level, pass only a collection of project refs to this method
 byte[] contentsProj = alsbcore.exportProjects(Collections.singleton(Ref.DEFAULT_PROJECT_REF),null);

 // 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.SERVICE_URI), // 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
         );
 //create a customization object for finding and replacing an environment value
 FindAndReplaceCustomization replaceCust = new FindAndReplaceCustomization("Find and Replace service uri",evquery, "productionhost");
 List custList = new ArrayList();
 custList.add(replaceCust);
 //customize now
 alsbSession.customize(custList);

 // 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 confirm 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);
    }
}
//Create a customization to assign a new set of env values
EnvValueCustomization envCust = new EnvValueCustomization("Assign env values", envValuesToChange);
custList.clear();
custList.add(envCust);
// customize now
alsbSession.customize(custList);
 

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 "http" services.

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

 // find all proxy services using http transport and WSDL based
 query.setTransportScheme("http");
 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 java.lang.String NAME
           
static java.lang.String TYPE
           
 
Method Summary
 void clone(Ref sourceRef, Ref targetRef)
          Clones a given source project, folder or resource with a new identity.
 void createFolder(Ref folderRef, java.lang.String description)
          Creates a folder with the given reference and description.
 void createProject(Ref projectRef, java.lang.String description)
          Creates a project with the given reference, and project description.
 void customize(java.util.List<Customization> customizations)
          This API supports multiple customizations at one place.
 void delete(java.util.Collection<Ref> refs)
          Deletes the given collection of references.
 boolean exists(Ref ref)
          Returns true if an entity exists in the domain.
 byte[] export(java.util.Collection<Ref> refsToExport, boolean includeDependencies, java.lang.String passphrase)
          Exports the given collection of references and returns bytes that make up the export data.
 byte[] exportProjects(java.util.Collection<Ref> projectrefs, java.lang.String passphrase)
          Export resources at the project level.
 java.util.Collection<QualifiedEnvValue> findEnvValues(EnvValueQuery query)
          Searches environment specific values based on the given query
 java.util.Map<Ref,Diagnostics> getDiagnostics(java.util.Collection<Ref> refs)
          Obtains diagnostic information about the given resources.
 java.lang.Object getEnvValue(Ref ref, java.lang.String envType, java.lang.String location)
          returns the environment value with the given type and location in the given resource.
 ALSBJarInfo getImportJarInfo()
          Returns detailed information about the entities in the previously staged configuration jar file
 java.util.Set<Ref> getRefs(BaseQuery query)
          Searches for resources using the given query and returns a set of refs.
 java.util.Set<Ref> getRefs(Ref root)
          Returns all the resources, folders or projects that are under the given root.
 java.lang.String getSession()
          Returns the name of the session that this mbean operates on
 ImportResult importUploaded(ALSBImportPlan importPlan)
          Import an already uploaded jar file in this session.
 BulkImportResult importZip(Ref location, byte[] zipcontent, java.util.Map<java.lang.String,java.lang.String> extensions)
          Imports the resources from a zip file.
 java.util.Set<Ref> mapReferences(java.util.Collection<Ref> resourcesToConsider, java.util.Map<Ref,Ref> refMap)
          Modifies the existing references from all the resources in the given list (resourcesToConsider) to a new set of references passed in the refMap.
 void move(Ref source, Ref target)
          This method is used to change the identity of a resource or to map an existing project or folder to another project or folder.
 java.util.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 java.lang.String NAME
See Also:
Constant Field Values

TYPE

static final java.lang.String TYPE
Method Detail

getSession

java.lang.String getSession()
Returns the name of the session that this mbean operates on

Returns:
the name of the session that this mbean operates on
Since:
2.5

getRefs

java.util.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
java.lang.IllegalArgumentException - if the root is null, or is a resource reference.
Since:
2.5

getDiagnostics

java.util.Map<Ref,Diagnostics> getDiagnostics(java.util.Collection<Ref> refs)
                                              throws java.lang.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:
java.lang.Exception
Since:
2.5

export

byte[] export(java.util.Collection<Ref> refsToExport,
              boolean includeDependencies,
              java.lang.String passphrase)
              throws java.lang.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:
java.lang.IllegalArgumentException - if arguments are not valid
java.lang.Exception - if export fails due to any other reason
Since:
2.5

uploadJarFile

java.util.Set<Ref> uploadJarFile(byte[] data)
                                 throws java.lang.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(com.bea.wli.sb.management.importexport.ALSBImportPlan) method.

Parameters:
data - contents of a previously exported configuration jar file.
Returns:
set of references to resources found in the jar file
Throws:
java.lang.Exception
Since:
2.5

findEnvValues

java.util.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.
Since:
2.5

clone

void clone(Ref sourceRef,
           Ref targetRef)
           throws AlreadyExistsException,
                  NotFoundException,
                  CreateException
Clones a given source project, folder or resource with a new identity. The clone operation allows user to clone the artifact into an arbitrary location with an arbitrary name. For example a resource "P1/F1/resourceA" can be cloned as "P2/F2/F3/resourceB"

Cloning a resource simply creates a copy of that resource with the given target identity. The clone will remain to have the same references as the original one. Moreover any other resources that were referencing the original resource will continue to reference the original. (This behavior is different when cloning a project or folder).

Cloning a location (project or folder) works differently from cloning a resource. It effectively clones all artifacts under that location (including folders) to a different location. Moreover the following are also performed.

Parameters:
sourceRef - the reference to the resource, project or folder to be cloned.
targetRef - the new identity of the cloned resource, project or folder. If the sourceRef is a resource, the targetRef must be of the same resource type. If sourceRef is a location (project or folder) the targetRef must be a location too. However the user can specify a folder in the sourceRef and a project as the targetRef, or vice versa. The former effectively promotes a folder to be a project, whereas the latter demotes a project to be a folder.
Throws:
AlreadyExistsException - if the target resource, project or folder (targetRef) already exists
NotFoundException - if the source is not found or if the parent location (project or folder) of the targetRef does not exist. For example if a folder "P1/sourceFolder" is to be cloned as "P2/F2/F3/targetFolder" the parent location, which is "P2/F2/F3" must exist.
CreateException - if there is any other error while creating a resource.
Since:
2.6

mapReferences

java.util.Set<Ref> mapReferences(java.util.Collection<Ref> resourcesToConsider,
                                 java.util.Map<Ref,Ref> refMap)
                                 throws NotFoundException,
                                        UpdateException
Modifies the existing references from all the resources in the given list (resourcesToConsider) to a new set of references passed in the refMap. refMap is validated first for any invalid or cyclic references. resourcesToConsider can also contain Project or Folder, in which case all the resources in that project or folder are modified with the new set of references passed in the refMap.

Parameters:
resourcesToConsider - list of resources to be modified with the new references
refMap - map of references. key is the old ref and value is the new ref
Returns:
the set of refs to resources that were changed
Throws:
java.lang.IllegalArgumentException - if the refMap is not valid
NotFoundException - if the resource given in the resourcesToConsider does not exist
UpdateException - if there is any error while trying to update the resources
Since:
2.6

getRefs

java.util.Set<Ref> getRefs(BaseQuery query)
                           throws NotFoundException
Searches for resources using the given query and returns a set of refs.

Parameters:
query - You can pass either ResourceQuery or DependencyQuery.
Returns:
the resulted resources as a set of refs
Throws:
NotFoundException - if a resource to a reference is not found
Since:
2.6

importZip

BulkImportResult importZip(Ref location,
                           byte[] zipcontent,
                           java.util.Map<java.lang.String,java.lang.String> extensions)
                           throws java.lang.Exception
Imports the resources from a zip file. This method tries to import all the resources in the zip file. The zip file can contain the following types: WSDL, XML Schema, XQuery, XSLT, WS-Policy, MFL and Archive. Use ZipUtils.getDefaultExtensionMap() method to get the default extension to resource mapping.
Name of the resource will be the name of the file with out the extension. If the resource is under a directory in the zip file, the same directory structure is created under the project or folder represented by location attribute.
If an extension is not mapped to any supported resource (or if there is no extension), those resources cannot be imported. The reason for failure can be obtained from the return value. Ref for these files in the Diagnostics will be null.
If the resource already exists, it will be updated. Otherwise it will be created.

Parameters:
location - the reference of the project or folder that will receive the resources. If the location does not exist it throws NotFoundException.
zipcontent - the byte content of the zip file to load
extensions - the map used to associate a file to a given resource type. If this is null we would use a default extension map.
Returns:
Map this map contains the file name and a diagnostics. This will have the entries for both succesfully imported files and failed ones.
Throws:
java.lang.IllegalArgumentException - if the file is not a valid zip file
NotFoundException - if the location specified doesn't exist
java.lang.Exception - If there is any exception during import
Since:
2.6

exportProjects

byte[] exportProjects(java.util.Collection<Ref> projectrefs,
                      java.lang.String passphrase)
                      throws java.lang.Exception
Export resources at the project level. A jar file that contains resources exported at the project level behaves differently from a jar file exported at the resource level (via export(java.util.Collection, boolean, java.lang.String) when imported to a target domain. Resource that are in the target domain, but not in the jar file are deleted by default. This behavior could be overwritten or customized by modifying the import plan. Folders are not deleted even if they don't exist in the jar file.

Parameters:
projectrefs - references to projects to be exported
passphrase -
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:
java.lang.Exception
Since:
2.6

importUploaded

ImportResult importUploaded(ALSBImportPlan importPlan)
                            throws java.lang.Exception
Import an already uploaded jar file in this session.

Parameters:
importPlan - ALSBImportPlan. A null value causes the default plan to be used.
Returns:
ImportResult object that contains resources that are successfully imported, deleted and those that have failed
Throws:
java.lang.Exception
Since:
2.6

getImportJarInfo

ALSBJarInfo getImportJarInfo()
                             throws NotFoundException,
                                    java.lang.Exception
Returns detailed information about the entities in the previously staged configuration jar file

Returns:
Throws:
NotFoundException - if no configuration jar has been uploaded, or a previously uploaded jar file has been imported
java.lang.Exception
Since:
2.6

customize

void customize(java.util.List<Customization> customizations)
               throws java.lang.Exception
This API supports multiple customizations at one place. As of now, you can do one of the following or any combinations of these: Assign Env Values | Find and Replace Env Values | Reference Mapping

Parameters:
customizations - Customization
Throws:
java.lang.Exception
Since:
2.6

move

void move(Ref source,
          Ref target)
          throws NotFoundException,
                 AlreadyExistsException,
                 UpdateException
This method is used to change the identity of a resource or to map an existing project or folder to another project or folder. Both source and target should point to a resource or to a project/folder, else an IllegalArgumentException is thrown. This method can be used to change the identity of an existing resource so that its name, or its location, or both are different. It can also be used to rename and/or move a resource. While changing the identity of a resource, all the references to this resource from other resources will be updated. This method can be used to map an existing project or folder to another project or folder. Mapping causes all subfolders and resources under the source to be moved to the target location. Certain mappings are simple renames of folders or projects, whereas others could be more elaborate move operation that may result in merging resources. A project can be mapped to a folder, or a folder can be mapped to a project. It is also possible to map a source location to an existing target location so that both are merged under the identity of the target location. Mapping a location to one of its descendants is not allowed (e.g., A/B/C cannot be mapped to A/B/C/D). However a location can be mapped to one of its ancestors (e.g., A/B/C can be mapped to A/B)

More precisely a mapping from A1/A2/.../An to B1/B2/.../Bm will change identity of all projects, folders, and resources under A1/A2/.../An (inclusive) to have a location prefix of B1/B2/.../Bm. For example if there is a folder A1/A2/.../An/Foo, it will become B1/B2/.../Bm/Foo.

Parameters:
source - reference to the source project/folder/resource
target - reference to the target project/folder/resource
Throws:
NotFoundException - is source or target ref is not found
AlreadyExistsException - while moving resources if another resource with the target's identity already exists. And while moving location if a resource in the source location conflicts with another resource with the same name in the target location.
UpdateException - any other failure is wrapped inside this exception.
Since:
2.6

delete

void delete(java.util.Collection<Ref> refs)
            throws NotFoundException,
                   DeleteException
Deletes the given collection of references. The collection can contains a mixture of resource references as well as projects or folders. All projects and folders are expanded and all resources within those locations are deleted as well. A Resource is deleted even if there are references to it.

Parameters:
refs - the collection of references to delete
Throws:
NotFoundException - if a reference is not found
DeleteException - if there is any error while deleting a resource. For example, if the user tries to delete System Project
Since:
2.6

createProject

void createProject(Ref projectRef,
                   java.lang.String description)
                   throws AlreadyExistsException,
                          CreateException
Creates a project with the given reference, and project description.

Parameters:
projectRef - reference to the project being created
description - description associated with the project
Throws:
CreateException - if there is any error while creating project
AlreadyExistsException - if the project user is trying to create already exists
java.lang.IllegalArgumentException - if the ref is not a project ref
Since:
2.6

createFolder

void createFolder(Ref folderRef,
                  java.lang.String description)
                  throws AlreadyExistsException,
                         NotFoundException,
                         CreateException
Creates a folder with the given reference and description.

Parameters:
folderRef - reference to a folder
description - description associated with the folder.
Throws:
CreateException - if a folder with the same name under the given parent exists.
AlreadyExistsException - if the project user is trying to create already exists
NotFoundException - if the parent of folderRef doesn't exist
java.lang.IllegalArgumentException - if the ref is not a folder ref
Since:
2.6

getEnvValue

java.lang.Object getEnvValue(Ref ref,
                             java.lang.String envType,
                             java.lang.String location)
                             throws NotFoundException
returns the environment value with the given type and location in the given resource.

Parameters:
ref - resource ref
envType - environment value type
location - environment value location
Returns:
environment value
Throws:
NotFoundException - if the resource is not found

exists

boolean exists(Ref ref)
Returns true if an entity exists in the domain. The entity can be a project, folder, or a resource

Parameters:
ref - reference to the entity
Returns: