com.bea.wli.management
Interface DeploymentMBean

All Superinterfaces:

weblogic.management.provider.Service

public interface DeploymentMBean
extends weblogic.management.mbeanservers.Service

This MBean allows clients to obtain/deploy Service Bus configuration information from/to a Service Bus domain. Service Bus configuration is packaged as a simple jar file. The jar file contains Service Bus artifacts, such as proxy services, WSDLs, Business Services etc. The configuration jar file can span multiple projects, and may contain partial configuration information. For example, the user can export just a subset of a project, a whole project, or subsets of resources from many projects. There is no restriction on what the configuration jar file may contain. An end-to-end deployment scenario typically proceeds as follows:

• Initial creation of Service Bus artifacts: The user first creates Service Bus artifacts using the Service Bus console.
• Exporting Service Bus artifacts: The user then exports all or a subset of these artifacts using the console or using the export related API of this MBean. The result of the export is a jar file that contains the exported artifacts, which also includes certain metadata about the artifacts.
• Creating a session: Before a configuration jar file can be imported the user must create a session. All Service Bus configuration changes (except for the security related changes) require a session. Sessions allow batching many updates together, and then committing them as one single unit.
• Importing Service Bus artifacts: The user imports all or a subset of resources inside of a configuration jar file into the session that has been created.
• Modifying environment specific values: Values of certain properties of Service Bus artifacts depend on the domain where they are created, and needs to be changed when moving the artifact from testing to staging to production domain. Deployment MBean provides a find and replace functionality to perform wholesale text substitution of these properties. Only certain propertes (such as service URIs and file directory names) can be changed in this way. Service Bus console must be used if a finer grained, or more complex changes needs to be made.
• Committing the session: The user finally commits the session and makes the changes permanent.

Obtaining DeploymentMBean

The following code sample shows how to obtain DeploymentMBean assuming you already have an MBean Server connection:

 import weblogic.management.mbeanservers.domainruntime.DomainRuntimeServiceMBean;
 import weblogic.management.jmx.MBeanServerInvocationHandler;
 import javax.management.MBeanServerConnection;

 // obtain mbean server connection
 MBeanServerConnection mbconn = ...

 // first obtain the WLS DomainRuntimeServiceMBean
 DomainRuntimeServiceMBean serviceMBean = (DomainRuntimeServiceMBean) MBeanServerInvocationHandler.
     newProxyInstance(mbconn, new ObjectName(DomainRuntimeServiceMBean.OBJECT_NAME));

 // then obtain Service Bus DeploymentMBean
 DeploymentMBean mbean = (DeploymentMBean)
     serviceMBean.findService(DeploymentMBean.NAME, DeploymentMBean.TYPE, null);

 

Exporting configuration

DeploymentMBean provides two different API, export and exportAll for exporting configuration data. The export method allows the user to export a targeted set of resources, whereas exportAll exports all the resources in a Service Bus domain. Both methods have two versions (with slightly different signatures).

One version returns a byte array that make up the contents of the exported jar file (See export(String[], Ref[], boolean) and exportAll()). The caller of these methods can simply save the byte array in any file, or simply pass it as import data to another Service Bus domain.

The second version (export(File, String[], Ref[], boolean) and exportAll(File)) simply passes a File object as an argument to these methods, so that the contents of the exported jar is saved into the given file. You can use this version only when the client invoking the mbean and the Admin server are on the same physical machine.

Export api always exports the definitions from the core state as opposed to a session. This is the state which the server runs on.

The following example uses the first version to export all the resources in project A, and one addition service outside project A.

 Ref myServiceRef = Ref.makeServiceRef(myProject, "myService");
 byte[] bytes = mbean.export(new String[] {"A"}, new Ref[] {myServiceRef}, true);
 

Importing Configuration

Similar to Exporting configuration, the import API accept either File or byte array as arguments. Unlike export API, the import API imports configuration into a session, rather than directly into core state. You can open a session, import as many configuration into the session as you want, perform modifications, and then commit the session. The following example shows a simple scenario.

 // first obtain a session
 String session = mbean.openImportSession();

 // then import into session only the resources that are in project A
 mbean.importIntoSession(session, bytes, new String[] {"A"}, null);

 // then replace the substring 'localhost' in the
 // service URIs with string 'productionhost'
 int numReplaced = mbean.findAndReplaceEnvValues(session,
                     TypeIds.URI_ENV_VALUE_TYPE,
                     "localhost",
                     "productionhost");

 // finally submit
 if (mbean.isSessionReadyForCommit(session)) {
     mbean.commitImportSession(session);
 } else {
     // notify the user. When this happens the user has to log in to the
     // Service Bus console and see what errors exist with the session
     System.out.println("There are problems with the imported file.");
     System.out.pritln("Session " + session + "cannot be committed.");
 }

 

Field Summary

static String	NAME
static String	TYPE

Method Summary

void	commitImportSession(String session) Commits the given session, effectively saving the contents of the session to the core state.
void	discardImportSession(String session) Discards the given session.
void	export(File jarfile, String[] projects, Ref[] resources, boolean includeDependencies) Convenience method for exporting resources to the given jar file.
byte[]	export(String[] projects, Ref[] resources, boolean includeDependencies) Exports resources and returns the contents of the jar file.
byte[]	exportAll() Exports all resources in the domain the jar file.
void	exportAll(File jarfile) Convenience method for exporting all resources in the domain to the given jar file.
int	findAndReplaceEnvValues(String session, String envValueType, String stringToReplace, String replacement) changes environment values by finding strings within them and replacing the substrings with the given replacement.
void	importIntoSession(String session, byte[] contentsOfJarFile) Imports all resources that are contained in the given jar file into a session
void	importIntoSession(String session, byte[] contentsOfJarFile, String[] projects, Ref[] resources) Imports selected resources from the given jar file into a session.
void	importIntoSession(String session, File jarfile) Convenience method for importing selected resources that are contained in the given jar file into a session
void	importIntoSession(String session, File jarfile, String[] projects, Ref[] resources) Convenience method for importing selected resources from the given jar file into a session.
boolean	isSessionReadyForCommit(String session) Returns true if the session has no conflicts and can be committed successfully.
String	openImportSession() Opens a session for staging one or more configuration jar files.

Methods inherited from interface weblogic.management.mbeanservers.Service

getName, getParentService, getType

Field Detail

NAME

static final String NAME

See Also:

Constant Field Values

TYPE

static final String TYPE

Method Detail

export

byte[] export(String[] projects,
              Ref[] resources,
              boolean includeDependencies)
              throws Exception

Exports resources and returns the contents of the jar file. The response can be saved into a jar file verbatim.

Parameters:

projects - projects to export. This is a convenience parameter for exporting all resources in a particular project without having to enumerate the resources. This argument can be null or empty array.

resources - resources to export along with any resources that are exported as a result of exporting projects. This argument can be used to export resources selectively without having to export a whole project

includeDependencies - if true, all resources that are required by the resources explicitly given are also exported.

Returns:

the byte contents of the jar that is created

Throws:

Exception

exportAll

byte[] exportAll()
                 throws Exception

Exports all resources in the domain the jar file. The response can be saved into a jar file verbatim.

Throws:

Exception

exportAll

void exportAll(File jarfile)
               throws Exception

Convenience method for exporting all resources in the domain to the given jar file. This method should only be used if the caller is on the same physical machine as the admin server.

Parameters:

jarfile - the jar file where the exported data will be stored

Throws:

Exception

export

void export(File jarfile,
            String[] projects,
            Ref[] resources,
            boolean includeDependencies)
            throws Exception

Convenience method for exporting resources to the given jar file. This method should only be used if the caller is on the same physical machine as the admin server. The contents of the jar file is obtained from the jarfile argument on the server.

Throws:

Exception

See Also:

export(String[], com.bea.wli.config.Ref[], boolean)

openImportSession

String openImportSession()
                         throws Exception

Opens a session for staging one or more configuration jar files. One can open multiple sessions and interact with them separately.

Returns:

the name of the session that is opened. THis session name should be passed to other methods that require a session name

Throws:

Exception

isSessionReadyForCommit

boolean isSessionReadyForCommit(String session)
                                throws Exception

Returns true if the session has no conflicts and can be committed successfully. Returns false otherwise.

Parameters:

session - name of the session

Returns:

Throws:

Exception

commitImportSession

void commitImportSession(String session)
                         throws Exception

Commits the given session, effectively saving the contents of the session to the core state. The session is automatically discarded after the commit finishes, regardless of the success status.

Parameters:

session - name of the session.

Throws:

Exception - if the commit fails.

discardImportSession

void discardImportSession(String session)
                          throws Exception

Discards the given session.

Parameters:

session - name of the session

Throws:

Exception

importIntoSession

void importIntoSession(String session,
                       File jarfile,
                       String[] projects,
                       Ref[] resources)
                       throws Exception

Convenience method for importing selected resources from the given jar file into a session.

Parameters:

session - the name of the session to import into

jarfile - the jar file to import

projects - projects whose resources will be imported into session. This is a convenience argument for importing all the resources in a project.

resources - resources that will be imported into the session, in addition to any resources that are already imported via the projects argument.

Throws:

Exception - if the given projects or resources are not found, or if the import fails due to another reason.

importIntoSession

void importIntoSession(String session,
                       File jarfile)
                       throws Exception

Convenience method for importing selected resources that are contained in the given jar file into a session

Parameters:

session - the name of the session to import into.

jarfile - the name of the jar file

Throws:

Exception - if the import fails.

importIntoSession

void importIntoSession(String session,
                       byte[] contentsOfJarFile,
                       String[] projects,
                       Ref[] resources)
                       throws Exception

Imports selected resources from the given jar file into a session.

Parameters:

session - the name of the session to import into

contentsOfJarFile - byte contents of the jar file that is being imported

projects - projects whose resources will be imported into session. This is a convenience argument for importing all the resources in a project.

resources - resources that will be imported into the session, in addition to any resources that are already imported via the projects argument.

Throws:

Exception - if the given projects or resources are not found, or if the import fails due to another reason.

importIntoSession

void importIntoSession(String session,
                       byte[] contentsOfJarFile)
                       throws Exception

Imports all resources that are contained in the given jar file into a session

Parameters:

session - the name of the session to import into.

contentsOfJarFile - byte contents of the jar file that is being imported

Throws:

Exception - if the import fails.

findAndReplaceEnvValues

int findAndReplaceEnvValues(String session,
                            String envValueType,
                            String stringToReplace,
                            String replacement)
                            throws Exception

changes environment values by finding strings within them and replacing the substrings with the given replacement.

Parameters:

session - the name of the session in which to perform substitutions

envValueType - the type of environment values to change.

stringToReplace - substring to replace

replacement - the replacement string.

Returns:

number of environment value instances that are affected

Throws:

Exception