This document includes the following topics:
Note: | Documentation for all BEA products, including BEA AquaLogic™ Service Bus documentation, is available on the BEA Product Documentation Web site. |
BEA AquaLogic Service Bus is an Enterprise-class service bus that connects, manages, and mediates interactions between heterogeneous services. AquaLogic Service Bus accelerates service configuration, integration, and deployment, thus simplifying management of shared services across the SOA.
AquaLogic Service Bus is policy-driven and enables loose coupling between service clients (service consumers) and business services (service providers). It provides a point of security control, monitoring, and Service Level Agreement (SLA) enforcement. Changes to service integration relationships are implemented dynamically through configuration, not code, allowing you to evolve and customize your service architectures with respect to security, service location, availability, data formats, monitoring, transports, communications, and so on.
As part of an enterprise messaging fabric, AquaLogic Service Bus can be used horizontally across many applications and systems, potentially spanning service implementations built by different teams in different departments. AquaLogic Service Bus separates a set of management functions from the service implementations, thus allowing the implementations to evolve independently and dynamically as driven by the needs of the business without requiring costly infrastructure development efforts.
For more information about AquaLogic Service Bus concepts and architecture, see BEA AquaLogic Service Bus Concepts and Architecture.
AquaLogic Service Bus 2.6 incorporates new functionality and enhancements in the following key areas:
In AquaLogic Service Bus 2.6 a database lookup function is introduced using a new XQuery function in the BEA XQuery engine. This can be used for message enrichment, for routing decisions or for customizing the behavior of a proxy service.
This read-access to databases from proxy services is supported without requiring you to write a custom EJB or custom Java code and without the need for a separate database product like AquaLogic Data Services Platform. You can use the execute-sql()
function to make a JDBC call to a database to perform simple database reads. Any SQL query is legal, from a query that gets a single tax rate for the supplied location to a query that does a complex join to obtain an order's current status from several underlying database tables.
See Accessing Databases Using XQuery in Modeling Message Flow in AquaLogic Service Bus in the AquaLogic Service Bus User Guide.
AquaLogic Service Bus 2.6 provides optimized transport for 1-way or 2-way communication for invoking services on AquaLogic Data Services Platform Data using a native Data Services Platform (DSP) transport. This allows a more efficient and flexible approach to accessing data services than exposing them as Web services via WebLogic Workshop and Java Web Services (JWS), and it supports security and identity propagation.
For information about the DSP transport, see Accessing Data Services Via AquaLogic Service Bus 2.6.
There are several ways to authenticate a client's identity in AquaLogic Service Bus—using Basic Authentication, client certificates (2-way SSL), and Web Service Security. In 2.6, client-specified custom authentication credentials for both transport- and message-level inbound requests are supported. The custom authentication credentials can be in the form of tokens, or a username and password token combination.
AquaLogic Service Bus accepts and attempts to authenticate:
The custom authentication mechanisms work alone or in concert with the message-level security for Web services.
See Configuring Custom Authentication in the AquaLogic Service Bus Security Guide.
In 2.6, you can keep the service definitions in AquaLogic Service Bus synchronized (both ways) with those in UDDI.
Services can be automatically published to a UDDI registry after they are created or changed within AquaLogic Service Bus and business service definitions can be imported from UDDI. In 2.6, support is added for the automatic update (requires no human intervention) of business services in AquaLogic Service Bus, when the original service is changed in UDDI. Alternatively, the AquaLogic Service Bus Console can be configured to prompt users for approval for synchronization when a service changes in the UDDI registry.
See UDDI in the AquaLogic Service Bus User Guide and the AquaLogic Service Registry documentation.
The EJB transport leverages the WebLogic Server JAX-RPC stack to perform Java to XML bindings. The JAX-RPC stack is a high performance engine that supports advanced Java objects such as XML Beans. If the Java type is not recognized by the stack, an extension mechanism (using converter classes) is provided to facilitate support of these Java types. The use of converter classes for EJB services is simplified in AquaLogic Service Bus 2.6—you can register a JAR file containing the converter classes as an AquaLogic Service Bus resource and subsequently use these classes to help map parameter and return value types to Java classes that can be mapped to XML. In previous releases, you had to package these converter classes in the EJB client JAR—that is the JAR containing the client stubs. See EJB Transport in the AquaLogic Service Bus User Guide.
For restrictions on UNIX platforms, see CR306913 in Known and Resolved Issues.
AquaLogic Service Bus 2.6 adds support for SOAP 1.2 Web Services. This includes accepting SOAP 1.1 messages and converting them to SOAP 1.2 messages when necessary to invoke a SOAP 1.2 business service, and vice versa. The following table outlines the support for SOAP 1.1 and SOAP 1.2 services with various platforms.
A number of APIs are exposed in 2.6 to allow customization of service definitions, WSDLs, schemas, XQueries and other design-time resources through programmatic interfaces. The supporting APIs allow loading ZIP files containing resources, in addition to moving, renaming, cloning, or deleting resources, folders and projects. A typical use case is one in which you have a prototypical proxy service from which you make a number of copies—each copy can be modified programmatically in some way.
For more information, see AquaLogic Service Bus APIs in the AquaLogic Service Bus User Guide.
You can use Java programs or scripts to automate deploying an application or for moving a configuration from staging to production.
Numerous customization options can be applied during deployment. An extended list of environment variables allows you to preserve or tailor settings when moving from one environment to another.
See the ALSBConfigurationMBean
Interface at the following URL:
Import customizations are supported by use of the ALSBImportPlan. For information about the ALSBImportPlan, see
For more information about the deployment APIs, see
Using the Deployment APIs in the AquaLogic Service Bus Deployment Guide.
The AquaLogic Service Bus 2.6 Console is enhanced with options for deployment customizations. See “Finding and Replacing Environment Values” and “Creating Customization Files” in System Administration in Using the AquaLogic Service Bus Console.
The AquaLogic Service Bus Console is redesigned to tailor interactions in support of the tasks performed by a user in the operator (IntegrationOperator) role. Now, operational functions and settings are easily accessible in the console—operators can easily search for resources using the new SMart Search functionality, monitor SLA alerts, pipeline alerts, logs, reports, turn tracing on and off, and enable and disable services.
In 2.6, users can readily distinguish between SLA and pipeline alerts because the metrics reported for each are distinguished on the console and via the JMX monitoring APIs. New service-level and global flags have been introduced to control alerting (SLA & pipeline), reporting, and logging. It is now possible to have monitoring enabled while suppressing SLA alerts. AquaLogic Service Bus users in the role of operator have more privileges than in previous releases—they can edit operational settings, create new SLA alert rules, and create and edit alert destination resources.
A new document is provided to describe operational tasks in the console. See the AquaLogic Service Bus Operations Guide.
The Service Callout functionality has been enhanced in this release to be better aligned with routing and publishing capabilities and to support features such as RPC Encoding and URL replacement. For information about the Service Callout functionality, see “Constructing Service Callout Messages” in Modeling Message Flow in AquaLogic Service Bus in the AquaLogic Service Bus User Guide. To learn how to configure Service Callouts and other actions in the AquaLogic Service Bus Console, see Proxy Service: Actions in Using the AquaLogic Service Bus Console.
A new feature in 2.6 allows you to clone any AquaLogic Service Bus resource, project or folder. Cloning a resource creates a copy of that resource with the specified target identity. Cloning a project or folder copies all artifacts in the project or folder to a different location. See the Configuration MBean Interface in the Javadoc and Project Explorer in Using the AquaLogic Service Bus Console.
In 2.6, you can export and import entire projects in addition to exporting and importing resources. There are two types of operational values: Global Operational Settings and operational values for proxy and business services. Global Operational Settings is a resource located in the System project folder and can be exported like any other resource. In 2.6, you can preserve operational values from being overwritten during import. While importing, if the ‘Preserve Operational Values’ setting is specified, the operational settings in the importing domain are preserved. If ‘Preserve Operational Values’ is not specified, the values from the JAR file being imported are set in the domain.
BEA Format Builder tool is enhanced in this release to support EDIFACT escape characters. (The default escape character in EDIFACT is “?”). A new option is also provided to allow you to specify the length of fixed length strings as number of characters instead of number of bytes. Information about these enhancements is documented in MFL Transformation Enhancement to Support Use of Delimiter Escape Character at the following URL:
http://download.oracle.com/docs/cd/E13171_01/alsb/docs26/MFLEnhancement.pdf
This document supplements the Format Builder documentation at the following URL:
http://download.oracle.com/docs/cd/E13171_01/alsb/docs26/fbhelp
The following deployment APIs are deprecated in AquaLogic Service Bus 2.6:
public ImportResult importUploaded(Collection<Ref> refs, boolean includeDependencies, boolean preserveExistingEnvValues, String passphrase) throws Exception;
Deprecated in 2.6 in favor of:
ImportResult importUploaded(ALSBImportPlan importPlan)throws Exception;
Imports an already uploaded JAR file in the current session. See the ALSBConfigurationMBean
Interface at the following URL:
The latter API allows more import customizations via the ALSBImportPlan. For information about the ALSBImportPlan, see
The following environment values APIs are deprecated in AquaLogic Service Bus 2.6:
Find environment values as indicated by the query and replace all occurrences of the environment value pattern (as returned by EnvValueQuery.getSearchString()) with the given parameter.
public int replaceEnvValues(EnvValueQuery query, String replacement) throws Exception;
Deprecated in 2.6 in favor of:
customize(List <Customization> customizations) throws Exception
in the ALSBConfigurationMBean.
Use FindAndReplaceCustomization for modifying environment values by doing string substitutions.
Set one or more environment values directly
public void assignEnvValues(Collection<QualifiedEnvValue> envValues) throws NotFoundException, UpdateException;
Deprecated in 2.6 in favor of:
customize(List <Customization> customizations) throws Exception
in the ALSBConfigurationMBean.
Use EnvValueCustomization for environment value assignments.
The following sections summarize the supported configurations for AquaLogic Service Bus 2.6:
For information about supported operating systems, databases, drivers, browsers, plug-ins, and other hardware and software requirements, see Supported Configurations for AquaLogic Service Bus.
For information about installing AquaLogic Service Bus, see AquaLogic Service Bus Installation Guide.
For information about AquaLogic Service Bus 2.6 interoperability, including information about support for compliance with messaging standards including SOAP, HTTP, JMS, SMTP/POP/IMAP, FTP, SSL, XML, XML Schema, WSDL, WSRP, and WS-Security, see AquaLogic Service Bus Interoperability Support Matrix.
Two data transformation tools are installed when you install AquaLogic Service Bus and Workshop for WebLogic—the BEA XQuery Mapper plug-in for Eclipse 3.1 and Format Builder. Eclipse 3.1 and Format Builder are supported on Windows platforms only.
The following sections describe known problems in AquaLogic Service Bus 2.6, as well as problems that were resolved in 2.6. Entries include a description of the problem and a workaround or solution where appropriate. A notation in the Fixed In column indicates that the problem has been resolved:
A new SLA Alert may not fire if you change the order it appears in the list of alerts for a service in the AquaLogic Service Bus Console.
|
|||||
Updates to an EJB client JAR or an EJB converter JAR are not reflected in the deployed EJB transport-based business service.
Suppose you have an EJB transport-based business service that uses an EJB Client JAR file and a Converter JAR file. If you update the implementation in one of those dependent JAR files, AquaLogic Service Bus re-validates the business service, but because the interface has not changed, no errors are raised. However, AquaLogic Service Bus will not redeploy the EJB transport-based business service, so it will continue to contain the implementation from the previous version of the JAR file. The EJB endpoint needs to be redeployed to contain the updated JAR file implementation.
|
|||||
AquaLogic Service Bus fails to import an MFL file if the passLiteral attribute value (in the StructFormat) is any value other than "true" or "false"
In AquaLogic Service Bus 2.5, the
passLiteral field, which is defined as xs:boolean is not handled properly and the system generates an error similar to the following one while importing an MFL file containing a value for passLiteral other than “true” or “false”
|
|||||
A monitoring run-time exception can occur at startup for managed servers if activation notifications reach different managed nodes at different times
Failed to initialize statistics data structure after checkpoint #### due to java.lang.Exception: [WLI-Monitoring Runtime:473230]Aggregator rejected statistics reported by server <managerserver> with tick #### because the server snapshot version xxxx is not compatible with current snapshot version yyyy
|
|||||
Attributes on the SOAP envelope element may not be preserved when the message is modified in the pipeline.
Previously, insert, replace, delete and rename operations on $body or $header left attributes on the SOAP envelope unaffected (though not so for an assign to $body or $header). These attributes can include the
encodingStyle attribute or other custom attributes whose loss may have a serious impact on the processing of the message. However, namespace attributes are preserved in the message.
Workaround: Do not use attributes, other than namespace declarations, on the SOAP envelope. Instead, push these attributes (such as
soap:encodingStyle ) down to the SOAP Body element. When attributes are on the SOAP Body or Header element, they are fully exposed in the pipeline and under the control of the transformation operations.
|
|||||
AquaLogic Service Bus can successfully import services from a UDDI registry even if those services were created with a newer version of AquaLogic Service Bus. For example, services created in 2.6 can be published to UDDI and subsequently imported into 2.5.
This presents no problem if the proxy service published by the later version uses no features new in the later release—that it, the service can be imported and invoked in the earlier AquaLogic Service Bus version.
However, if a proxy service published by the later version uses features new in that version, it cannot be used in the earlier version. (for example, a SOAP1.2-based business service can be imported, but it does not work.)
It is also possible that a proxy service published by a later version of AquaLogic Service Bus differs in how it is published compared to how services were published from older versions. The service may be supported after import to the earlier version; however, the imported business service may need to be fixed after import (for example, in 2.6, there were changes to how transport security was published).
|
|||||
Due to hot deployment, the correct version of an invoked service's MFL or WSDL may not be properly seen by a proxy service that invokes that service.
|
|||||
Publishing to UDDI intermittently returns an error when you publish a service to AquaLogic Service Registry.
|
|||||
A single stand-alone JMS client cannot consume all messages on uniform distributed queues (UDQs) when the default ForwardDelay is set.
|
|||||
When you copy large files into an input directory in Windows, misleading errors are logged to the server log file.
In the Windows operating system, when you copy large files (for example, 100MB) into the input directory of a file transport proxy service, errors are logged in the server log file that state
"File cannot be moved from location <filename> to the stage directory. Current Process may not have permission to do this operation" . These errors may occur while the file is being copied. However, the file is processed successfully on the next polling cycle after the copy completes.
|
|||||
Do Not Use the Default System Prefix (soap-env) when Constructing a Non-System Fault in AquaLogic Service Bus
When you create a non-system fault in AquaLogic Service Bus, you cannot use the default system prefix (
soap-env ) for the namespace. You must declare a new namespace prefix and use it in the faultcode .
|
|||||
An AquaLogic Service Bus domain cannot boot and generates weblogic.transaction.loggingresource.LoggingResourceException if the domain is a new domain using the same database, schema, and LLR table as an existing domain.
When you move a domain template to a different machine and use the template to create the new domain, the new domain is not able to boot and weblogic.transaction.loggingresource.LoggingResourceException is thrown. The following details outline the scenario:
|
|||||
Workaround: You must use the same domain name when you create the new domain using the same template on a different machine. Alternatively, change the name of the LLR table that the new domain uses. You can configure this on the WebLogic Server Administration Console on a per Server basis, using the
JDBCLLRTableName attribute on the ServerMBean.
|
|||||
Keep the path of proxy services short for successful deployment on Windows machines because of a system path length limitation.
This limitation applies to both JMS proxy services and business services with responses. Because the generated proxy service EAR file is created in the domain directory, you should keep the path to the domain directory short. It is not necessary to keep the name of the proxy service or business service short.
The limit for the generated EAR file is 50 characters and the null terminator is 1 character. Therefore, in a single server domain, the domain directory path (including the following slash) may not exceed 209 characters. In a cluster domain, the domain directory path plus the name of any Managed Server may not exceed 142 characters.
|
Problem using AquaLogic Service Bus HTTP proxy services with web server WebLogic Server plug-ins when using SSL
Consider the scenario in which an HTTPS request (HTTP over SSL) comes into the web server front end; the WebLogic Server web server plug-in subsequently forwards that request to an AquaLogic Service Bus managed server containing an AquaLogic Service Bus HTTP proxy service.
The web server plug-in can be configured to forward the request over HTTP—that is, without using SSL. However, the AquaLogic Service Bus HTTP proxy service interprets the request as having come over HTTPS and rejects it. In this case, the server log shows an error of the form:
<Exception in HttpTransportServlet.service: javax.servlet.ServletException: Cannot process inbound request to endpoint ProxyService Project/folder/ProxyName over https
Workaround: Configure the proxy service with the HTTPS transport. Even though the message comes over the non-SSL port from the web server, AquaLogic Service Bus recognizes that the message originally used the HTTPS protocol and accepts the message as an HTTPS message. The SSL port in the AquaLogic Service Bus domain must be enabled to do this, even though it is not used in this scenario.
|
|||
AquaLogic Service Bus JMS services (proxy and business) have a “Use SSL” attribute that controls whether SSL should be used to access the JMS queues.
However, in AquaLogic Service Bus 2.5 and earlier, JMS business services did not use SSL when reading the outbound responses even if “Use SSL” was specified. This has been corrected in AquaLogic Service Bus 2.6.
However, this means that when a such business service (JMS request/response business service with “Use SSL” selected) from AquaLogic Service Bus 2.1 or 2.5 is imported into 2.6, there may be a problem if the outbound response URL corresponds to a non-SSL port. Attempts to use SSL to talk to this non-SSL port will result in an error.
|
|||
A security error in the server log occurs in both AquaLogic Service Bus and WebLogic Server. The error is as follows:
Workaround: Establish domain trust. When there is no cross-domain transaction, these security exceptions can occur for WebLogic Server 9.1 and earlier releases. For 9.2 to 9.2 cross clustered domain JMS/JNDI/RMI calls, this exception is intermittent. Workaround: Configure the JTA SecurityInteropMode to “Performance” in the WebLogic Server Administration Console for 9.x domains, and on the command line for older versions. For more information, see “Setting Security Interoperability Mode” in Configuring Domains for Inter-Domain Transactions in Programming WebLogic JTA. |
|||
AquaLogic Service Bus 2.5 service validation generates warnings when a policy bound to the service has unknown policy assertions. However, this release does not check for unknown policy assertions in WSDL or WS-Policy resources.
Workaround: Check for unknown WS-policy assertions in the WSDL. Ensure that the WSDL contains only valid assertion entries. For more information see
Using Web Services Policy to Specify Inbound Message Security in the Security guide.
|
|||
Intermittent Web Service Security timestamp validation errors: “Message is too old" or "Message Created time in the future."
A bug in the Web Service Security runtime causes intermittent timestamp validation errors when the message age is short and Clock Precision is specified.
Workaround: If you suspect you are having this problem, contact your BEA representative and request a patch for CR251516. (The Clock Precision property was deprecated and replaced by the more intuitive Clock Skew property.) See
CR251516 in the “Web Services and XML section of WebLogic Server 9.2 Known and Resolved Issues.
|
|||
Web Service Security username tokens can be used in various ways. The token may include a username and password or just a username. When a username token is used without a password, the Web service security runtime will only accept it if it is covered by a signature. If the token is not signed, the runtime will reject it. The configuration-time WS-Policy validator does not enforce this restriction in this release.
|
|||
A problem in the client-side Web Service Security runtime causes X.509 token authentication to fail in certain cases.
Make sure to include a dummy username token
CredentialProvider (see source code that follows) along with a ClientBSTCredentialProvider in the list of credential providers passed to the JAX-RPC client. The credential provider list is passed to the client as the value of the property named weblogic.wsee.security.wss.CredentialProviderList .
For more information, see “Updating a Client Application to Invoke a Message-Secured Web Service” under “Configuring Message-Level Security (Digital Signatures and Encryption)” in
Configuring Security in Programming Web Services for WebLogic Server.
|
|||
Before deleting, moving, renaming, cloning or deleting a proxy service (or deleting, renaming, or moving a project or folder (which, in effect, changes the URL for proxy services in the projects or folders)), delete all associated Transport-level (HTTP and HTTPS) and Service-level access control security policies.
Failure to delete these policies will leave the policies in the authorization-provider database and potentially cause unexpected results and potential security vulnerabilities, such as leaving unprotected a service which was previously protected. Note: that when you clone a service, access control policies are not cloned.
|
You cannot move an AquaLogic Service Bus configuration JAR file with encrypted resources exported with the Sun or JRockit JDK to the IBM AIX JDK and vice-versa.
There are differences in the various JDK implementations of the Password-Based Encryption algorithms used by AquaLogic Service Bus to protect resources with sensitive data. These differences cause import to fail when an encrypted resource created with the Sun or JRockit JDK is imported into the IBM JDK or vice versa.
For information about the encryption algorithms, see http://java.sun.com/j2se/1.5.0/docs/guide/security/jce/JCERefGuide.html#PBE).
|
|||
Using HTTP tunneling from an AquaLogic Service Bus 2.5 domain to access an EJB in a WebLogic Server 8.1 domain can result in exceptions.
Workaround: For HTTP tunneling between WebLogic Server 9.2 and WebLogic Server 8.1 to work, you must set the
t3-server-abbrev-table-size element to 255 in the config.xml file in the AquaLogic Service Bus domain (the 9.2 domain)
For more troubleshooting information about EJB transports, see
EJB Transport in the AquaLogic Service Bus User Guide.
|
|||
The Listing and Locating Access Control Policies topic provided in the online help that you launch from the AquaLogic Service Bus Console does not mention that you can create a message-level access control policy for proxy services that have message-level custom authentication.
|