Package 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 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 Details

  • Method Details

    • 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
      Since:
      2.5

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

    • 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
      Since:
      2.5

    • export

      @Deprecated byte[] export(Collection<Ref> refsToExport, boolean includeDependencies, String passphrase) throws Exception
      Deprecated.
      As of 12c, replaced by exportReferences.
      Exports the given collection of references and returns bytes that make up the export data. For security reasons, this method is deprecated. Use the * exportReferences method instead.
      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:
      IllegalArgumentException - if arguments are not valid
      Exception - if export fails due to any other reason
      Since:
      2.5

    • exportReferences

      byte[] exportReferences(Collection<Ref> refsToExport, boolean includeDependencies, char[] 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:
      IllegalArgumentException - if arguments are not valid
      Exception - if export fails due to any other reason
      Since:
      12c

    • 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(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:
      Exception
      Since:
      2.5

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

      Set<Ref> mapReferences(Collection<Ref> resourcesToConsider, 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:
      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

      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, Map<String,String> extensions) throws 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:
      IllegalArgumentException - if the file is not a valid zip file
      NotFoundException - if the location specified doesn't exist
      Exception - If there is any exception during import
      Since:
      2.6

    • exportProjects

      @Deprecated byte[] exportProjects(Collection<Ref> projectrefs, String passphrase) throws Exception
      Deprecated.
      As of 12c, replaced by exportProjectsReferences.
      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. For security reasons, this method is deprecated. Use the * exportReferences method instead.
      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:
      Exception
      Since:
      2.6

    • exportProjectsReferences

      byte[] exportProjectsReferences(Collection<Ref> projectrefs, char[] passphrase) throws 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:
      Exception
      Since:
      12c

    • importUploaded

      ImportResult importUploaded(ALSBImportPlan importPlan) throws 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:
      Exception
      Since:
      2.6

    • getImportJarInfo

      ALSBJarInfo getImportJarInfo() throws NotFoundException, 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
      Exception
      Since:
      2.6

    • customize

      void customize(List<Customization> customizations) throws 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:
      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(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

    • getProjects

      Set<Ref> getProjects()
      Returns:
      all the projects in the domain

    • createProject

      void createProject(Ref projectRef, 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
      IllegalArgumentException - if the ref is not a project ref
      Since:
      2.6

    • createFolder

      void createFolder(Ref folderRef, 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
      IllegalArgumentException - if the ref is not a folder ref
      Since:
      2.6

    • getEnvValue

      Object getEnvValue(Ref ref, String envType, 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: