Skip navigation links

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

public interface ALSBConfigurationMBean

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<Ref, Diagnostics> 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<Customization> custList = new ArrayList<Customization>();
 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<QualifiedEnvValue> envValuesToChange = new ArrayList<QualifiedEnvValue>();
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<Ref> 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.

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.

• a project can be cloned to be a folder, effectively demoting it (e.g., clone "P1" as "P2/f2").
• a folder can be cloned to be a project, effectively promoting it (e.g., clone "P1/f1", as "P2").
• a location (folder or project) can be cloned to be an existing location effectively merging two locations. In this case the contents are merged. For example if "P1/f1" is clones as "P2/f2" and both locations have some artifacts, the P2/f2 will have combined set of artifacts.
• location properties such as its description are copied (if the target location does not exist)
• all the resources that are cloned will have their references adjusted in the following manner: any reference to a resource that is also being cloned, will be changed so that it will reference the cloned resource and not the original resource. Any reference to a resource that is not being cloned as part of the clone operation (i.e., outside the source location) will remain the same.

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 <file extension / resource type> used to associate a file to a given resource type. If this is null we would use a default extension map.

Returns:

Map<String,Diagnostics> 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<com.bea.wli.config.Ref>, 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:

Skip navigation links