Contents

Title and Copyright Information

Preface

• Documentation Accessibility
• Conventions

1 Introduction and Roadmap

• Document Scope and Audience
• Guide to This Document
• Related Documentation
• Examples for the Resource Adapter Developer
• New and Changed Features in This Release

2 Understanding Resource Adapters

• Overview of Resource Adapters
  • Comparing WebLogic Server and WebLogic Integration Resource Adapters
  • Inbound, Outbound, and Bidirectional Resource Adapters
  • Comparing 1.0 Resource Adapters to 1.5 and 1.6
  • Connector Architecture 1.6 Support
  • Additional Support Provided by the WebLogic Server Connector Container
• Java EE Connector Architecture
  • Java EE Architecture Diagram and Components
  • System-Level Contracts
• Resource Adapter Deployment Descriptors

3 Creating and Configuring Resource Adapters

• Creating and Configuring Resource Adapters: Main Steps
• Modifying an Existing Resource Adapter
• Configuring the ra.xml File
  • Creating the ra.xml File Manually
  • Using Metadata Annotations to Specify Deployment Information
  • Resource Adapter XML Schema Definitions
• Configuring the weblogic-ra.xml File
  • Editing Resource Adapter Deployment Descriptors
    • Editing Considerations
    • Schema Header Information
    • Conforming Deployment Descriptor Files to Schema
  • Dynamic Descriptor Updates: Console Configuration Tabs
    • Dynamic Reconfigurable Configuration Properties
    • Dynamic Configuration Parameters
    • Dynamic Pool Parameters
    • Dynamic Logging Parameters
  • Automatic Generation of the weblogic-ra.xml File
  • (Deprecated) Configuring the Link-Ref Mechanism
• Bean Validation Configuration File
• Long-Running Work Support
• Tooling Support

4 Programming Tasks

• Required Classes for Resource Adapters
• Generic Work Context
  • Interfaces, Classes, and Methods Added to Support the Generic Work Context
  • Deployment Descriptor Element Added to Support the Generic Work Context
• Programming a Resource Adapter to Perform as a Startup Class
  • Minimum Content of a Resource Adapter
  • Submitting a Work Instance
  • Retrying a Work Submission
• Suspending and Resuming Resource Adapter Activity
• Extended BootstrapContext
  • Diagnostic Context ID
  • Dye Bits
  • Callback Capabilities
  • Bean Validation
  • BeanManager
• Administered Object Uniqueness

5 Using Contexts and Dependency Injection in Resource Adapters

• Overview
• Resource Adapter Bean Discovery
• Obtaining Contextual References to Resource Adapter Beans
• Invoking Resource Adapter Beans From Other Application Types
• Using Resource Adapters Deployed as CDI Bean Archives
  • BeanManager Support
  • Injection Points
• Using CDI with Resource Adapter Component Beans
  • Resource Adapter Component Beans Must Not Be Managed Beans
  • Using Dependency Injection
    • Notes on Injection Usage
    • Example

6 Connection Management

• Connection Management Contract
  • Connection Factory and Connection
  • Resource Adapters Bound in JNDI Tree
  • Obtaining the ConnectionFactory (Client-JNDI Interaction)
  • Specifying and Obtaining Transaction Support Level
  • Specifying an Unshareable ManagedConnectionFactory
• Configuring Outbound Connections
  • Connection Pool Configuration Levels
  • Retrying a Connection Attempt
  • Multiple Outbound Connections Example
• Configuring Inbound Connections
• Configuring Connection Pool Parameters
  • initial-capacity: Setting the Initial Number of ManagedConnections
  • max-capacity: Setting the Maximum Number of ManagedConnections
  • capacity-increment: Controlling the Number of ManagedConnections
  • shrinking-enabled: Controlling System Resource Usage
  • shrink-frequency-seconds: Setting the Wait Time Between Attempts to Reclaim Unused ManagedConnections
  • highest-num-waiters: Controlling the Number of Clients Waiting for a Connection
  • highest-num-unavailable: Controlling the Number of Unavailable Connections
  • connection-creation-retry-frequency-seconds: Recreating Connections
  • match-connections-supported: Matching Connections
  • test-frequency-seconds: Testing the Viability of Connections
  • test-connections-on-create: Testing Connections upon Creation
  • test-connections-on-release: Testing Connections upon Release to Connection Pool
  • test-connections-on-reserve: Testing Connections upon Reservation
• Connection Proxy Wrapper - 1.0 Resource Adapters
  • Possible ClassCastException
  • Turning Proxy Generation On and Off
• Reset a Connection Pool
• Testing Connections
  • Configuring Connection Testing
  • Testing Connections in the Administration Console

7 Transaction Management

• Supported Transaction Levels
  • XA Transaction Support
  • Local Transaction Support
  • No Transaction Support
  • Runtime Transaction Support Level Specification
• Configuring Transaction Levels
  • Configure XA Transaction Recovery Credential Mapping

8 Message and Transactional Inflow

• Overview of Message and Transactional Inflow
  • Architecture Components
  • Inbound Communication Scenario
• How Message Inflow Works
  • Handling Inbound Messages
  • Proprietary Communications Channel and Protocol
• Message Inflow to Message Endpoints (Message-driven Beans)
  • Deployment-Time Binding Between an MDB and a Resource Adapter
    • Binding an MDB and a Resource Adapter
  • Dispatching a Message
  • Activation Specifications
  • Administered Objects
• Transactional Inflow
  • Using the Transactional Inflow Model for Locally Managed Transactions
• Configuring and Managing Long-Running Work
  • Setting the Maximum Number of Concurrent Long-Running Work Instances
  • Monitoring Long-Running Work

9 Security

• Container-Managed and Application-Managed Sign-on
  • Application-Managed Sign-on
  • Container-Managed Sign-on
• Credential Mapping for Making Outbound Connections
  • Authentication Mechanisms
  • Outbound Credential Mappings
    • Non-initial Connection: Requires ManagedConnection from Adapter Upon Application's Request
    • Initial Connection: Requires a ManagedConnection from Adapter Without Application's Request
    • Special Users
  • Creating Outbound Credential Mappings Using the Console
• Security Inflow
  • Inbound Principal Mappings
  • Security Inflow Callback Requirements
  • Backward Compatibility with Connector Architecture 1.5 and 1.0
• Security Policy Processing
• Configuring Security Identities for Resource Adapters
  • default-principal-name: Default Identity
  • manage-as-principal-name: Identity for Running Management Tasks
  • run-as-principal-name: Identity Used for Connection Calls from the Connector Container into the Resource Adapter
  • run-work-as-principal-name: Identity Used for Performing Resource Adapter Management Tasks
• Configuring Connection Factory-Specific Authentication and Re-authentication Mechanisms

10 Packaging and Deploying Resource Adapters

• Packaging Resource Adapters
  • Packaging Directory Structure
  • Packaging Considerations
  • Packaging Limitation
  • Packaging Resource Adapter Archives (RARs)
• Deploying Resource Adapters
  • Deployment Options
  • Resource Adapter Deployment Names
  • Production Redeployment
    • Suspendable Interface and Production Redeployment
    • Production Redeployment Requirements
    • Production Redeployment Process

A weblogic-ra.xml Schema

• weblogic-connector
• work-manager
• connector-work-manager
• security
  • default-principal-name
  • manage-as-principal-name
  • run-as-principal-name
  • run-work-as-principal-name
  • security-work-context
    • caller-principal-default-mapped
    • caller-principal-mapping
    • group-principal-mapping
• properties
• admin-objects
  • admin-object-group
    • admin-object-instance
• outbound-resource-adapter
  • default-connection-properties
    • pool-params
    • logging
  • connection-definition-group
    • connection-instance

B Resource Adapter Best Practices

• Classloading Optimizations for Resource Adapters
• Connection Optimizations
• Thread Management
• InteractionSpec Interface
• Using javax.jms.ConnectionFactory