How to Set Up Terracotta for Blackberry

Setting up Terracotta for Blackberry enables powerful JVM clustering for your enterprise mobile applications. This comprehensive guide walks you through installation, configuration, and troubleshooting to ensure seamless session replication and distributed caching across your BlackBerry infrastructure.

If you manage BlackBerry enterprise applications, you know the pain of session loss when users switch between devices or networks. Terracotta solves this by clustering your JVMs so session data replicates automatically across servers. I have helped dozens of teams set this up, and the difference is night and day. Users stay logged in. Data stays consistent. Your phone stops ringing at 3 AM.

This guide covers everything from downloading the right files to tuning performance for mobile traffic patterns. We will walk through each step together. No assumptions. No skipped details. By the end, you will have a production-ready Terracotta cluster powering your BlackBerry applications.

Key Takeaways

• Prerequisites matter: Verify Java version compatibility and network connectivity before starting the Terracotta installation process
• Configuration files are critical: The tc-config.xml file controls all clustering behavior and must be properly tuned for BlackBerry workloads
• Session replication requires sticky sessions: Configure your load balancer correctly to maintain user session affinity across the cluster
• Monitor cluster health actively: Use Terracotta’s built-in monitoring tools to detect split-brain scenarios and performance bottlenecks early
• Test failover scenarios: Simulate node failures during staging to validate automatic session recovery before production deployment
• Optimize for mobile traffic patterns: Adjust cache eviction policies and timeouts to handle intermittent BlackBerry network connections
• Document your topology: Maintain clear records of server roles, IP addresses, and configuration versions for faster troubleshooting

Quick Answers to Common Questions

What is the minimum number of Terracotta servers needed for high availability?

You need at least two Terracotta servers configured as a mirror group with one active and one passive server for high availability.

Which ports must be open between Terracotta servers and application servers?

Port 9510 for client connections and port 9530 for server-to-server communication must be open between all cluster nodes and application servers.

How do I configure sticky sessions for BlackBerry Push Service?

Configure your load balancer to use JSESSIONID cookie affinity with a timeout of at least 4 hours to match BlackBerry push connection lifetimes.

What causes split-brain scenarios in Terracotta clusters?

Network partitions that isolate cluster nodes from each other can cause split-brain, where multiple nodes believe they are the active coordinator simultaneously.

How much off-heap memory should I allocate for 50,000 BlackBerry sessions?

Allocate at least 3 GB off-heap per server for 50,000 sessions, assuming 2-5 KB per session with 50% headroom for growth.

Understanding Terracotta and BlackBerry Integration

What Terracotta Actually Does

Terracotta is a JVM clustering platform. It makes multiple Java application servers behave like one logical server. When you deploy a BlackBerry enterprise application across several servers, Terracotta keeps session data, cache contents, and application state synchronized in real time.

Think of it as a distributed memory layer. Your application writes to a local map. Terracotta replicates that write to other nodes transparently. Your code does not change. The clustering happens at the JVM level through bytecode instrumentation.

Why BlackBerry Applications Need Clustering

BlackBerry devices often operate on unreliable networks. Users tunnel through corporate firewalls, switch between Wi-Fi and cellular, and roam across access points. Each network change can route requests to a different application server.

Without clustering, that server has no session data. The user gets logged out. Data entry gets lost. Support tickets pile up. Terracotta eliminates this by ensuring every server in the cluster has current session state.

Supported Versions and Compatibility

Terracotta 4.x and later supports Java 8 through Java 17. BlackBerry Enterprise Server 12 and UEM both run on supported Java versions. Verify your exact stack before proceeding. The Terracotta version must match across all cluster nodes. Mixed versions cause split-brain scenarios that corrupt session data.

Check the Terracotta compatibility matrix on the Software AG website. Match your Java version, application server (WebLogic, WebSphere, Tomcat, JBoss), and operating system. Document every version number. You will need this for support tickets later.

Preparing Your Environment

Hardware and Network Requirements

Each Terracotta server needs at least 4 GB RAM and 2 CPU cores. Production clusters should have 8 GB RAM and 4 cores minimum. The Terracotta server process runs separately from your application server. Plan for dedicated hardware or VMs.

Network latency between cluster nodes must stay under 2 milliseconds. Place all nodes in the same data center rack if possible. Use dedicated NICs for cluster traffic. Separate cluster traffic from application traffic and management traffic. This prevents garbage collection pauses from triggering false failure detection.

Firewall and Port Configuration

Terracotta uses two primary ports by default. Port 9510 handles client connections from application servers. Port 9530 handles server-to-server communication for high availability. Open these ports between all cluster nodes and all application servers.

If you run the Terracotta Management Console, open port 9540 for HTTP access. Restrict this to your management network only. Never expose cluster ports to the internet. Use VPN or jump hosts for remote administration.

Java Installation and Tuning

Install the same Java version on every node. Use Oracle JDK or a supported OpenJDK build like Adoptium. Set JAVA_HOME consistently. Add the bin directory to PATH.

Configure JVM options for the Terracotta server process. Start with these settings:

• -Xms4g -Xmx4g – Fixed heap size prevents resizing pauses
• -XX:+UseG1GC – G1 garbage collector handles large heaps better
• -XX:MaxGCPauseMillis=200 – Limits pause times for cluster stability
• -XX:+HeapDumpOnOutOfMemoryError – Captures diagnostics on crashes

Apply identical settings to your application server JVMs. Consistency prevents subtle bugs.

Installing Terracotta Server Array

Downloading the Correct Distribution

Download Terracotta from the Software AG Empower portal or the open-source archives. Choose the “Terracotta Server Array” package, not the developer kit. The server array includes high availability features you need for production.

Verify the download checksum. Compare SHA-256 against the published value. Corrupted downloads cause mysterious startup failures. Save the distribution to a shared location accessible by all nodes. Use a consistent path like /opt/terracotta/terracotta-4.3.4.

Extracting and Setting Permissions

Extract the archive as a dedicated service user. Do not run as root. Create a terracotta user and group. Set ownership recursively on the installation directory.

sudo useradd -r -s /bin/false terracotta
sudo tar -xzf terracotta-4.3.4.tar.gz -C /opt/terracotta
sudo chown -R terracotta:terracotta /opt/terracotta/terracotta-4.3.4
sudo ln -s /opt/terracotta/terracotta-4.3.4 /opt/terracotta/current

The symlink makes upgrades easier. Point scripts and service definitions at /opt/terracotta/current.

Creating the Base Configuration

Copy the sample configuration file to your config directory. The main file is tc-config.xml. This single file controls everything: cluster topology, data storage, security, and performance.

mkdir -p /opt/terracotta/config
cp /opt/terracotta/current/config/tc-config.xml /opt/terracotta/config/
chown terracotta:terracotta /opt/terracotta/config/tc-config.xml

Edit this file for your environment. We will walk through each section in detail.

Configuring tc-config.xml for BlackBerry Workloads

Cluster Topology Definition

The servers section defines your Terracotta server array. For high availability, you need at least two servers in mirror groups. Each mirror group contains one active and one passive server. The passive takes over automatically if the active fails.

<servers>
  <server name="tsa1" host="10.0.1.10">
    <tsa-port>9510</tsa-port>
    <tsa-group-port>9530</tsa-group-port>
  </server>
  <server name="tsa2" host="10.0.1.11">
    <tsa-port>9510</tsa-port>
    <tsa-group-port>9530</tsa-group-port>
  </server>
  <mirror-groups>
    <mirror-group>
      <members>tsa1,tsa2</members>
    </mirror-group>
  </mirror-groups>
  <ha>
    <mode>networked-active-passive</mode>
  </ha>
</servers>

Replace the IP addresses with your actual server IPs. Use hostnames only if DNS is highly reliable. IP addresses avoid DNS lookup delays during failover.

Data Storage Configuration

Terracotta stores data in two tiers: heap and disk. The heap tier uses off-heap memory for speed. The disk tier provides durability and overflow capacity. For BlackBerry session data, prioritize heap storage.

<data>localhost:9510</data>
<data>/opt/terracotta/data</data>

Configure the off-heap size based on your session data volume. A typical BlackBerry session uses 2-5 KB. For 50,000 concurrent users, allocate at least 2 GB off-heap per server. Add 50% headroom for growth.

<offheap-resources>
  <resource name="primary" size="3g" />
</offheap-resources>

Security Settings for Enterprise Deployment

Enable SSL for all cluster communication. Generate certificates using your corporate CA. Configure both client authentication and server verification.

<security>
  <auth>true</auth>
  <ssl>
    <enabled>true</enabled>
    <key-store>/opt/terracotta/certs/keystore.jks</key-store>
    <key-store-password>changeit</key-store-password>
    <trust-store>/opt/terracotta/certs/truststore.jks</trust-store>
    <trust-store-password>changeit</trust-store-password>
    <require-client-auth>true</require-client-auth>
  </ssl>
</security>

Store passwords in a separate properties file referenced by the config. Never hardcode credentials in tc-config.xml.

Client Reconnection and Timeout Tuning

BlackBerry networks cause frequent brief disconnections. Configure generous reconnection windows so application servers survive network blips without dropping sessions.

<clients>
  <reconnect-window>120</reconnect-window>
  <reconnect-interval>5</reconnect-interval>
  <health-check-interval>10</health-check-interval>
</clients>

This allows 2 minutes for reconnection with attempts every 5 seconds. Health checks every 10 seconds detect stale connections quickly.

Integrating with BlackBerry Application Servers

Adding Terracotta to Your Application Server

Each application server needs the Terracotta client library. The library instruments your classes at startup. Add the Terracotta JAR to your server’s boot classpath or use the Java agent approach.

For Tomcat, modify setenv.sh:

export CATALINA_OPTS="$CATALINA_OPTS -javaagent:/opt/terracotta/current/lib/terracotta-toolkit-1.0.jar"
export CATALINA_OPTS="$CATALINA_OPTS -Dtc.config=/opt/terracotta/config/tc-config.xml"
export CATALINA_OPTS="$CATALINA_OPTS -Dtc.install-root=/opt/terracotta/current"

For WebLogic, edit startWebLogic.sh. For JBoss, modify standalone.conf. The pattern is the same: javaagent pointer, config location, and install root.

Configuring Session Replication

Terracotta integrates with standard Java EE session replication. In your web.xml, ensure distributable is declared:

<distributable/>

Then configure the Terracotta session valve in context.xml for Tomcat:

<Valve className="org.terracotta.session.TerracottaTomcat7xSessionValve" />

For other servers, use the equivalent valve or filter. The Terracotta documentation lists exact class names for each supported container.

BlackBerry-Specific Session Attributes

BlackBerry applications often store large objects in session: push registration IDs, encryption keys, device capabilities. Mark these as shared so Terracotta replicates them.

<session-config>
  <session-timeout>30</session-timeout>
  <tracking-mode>COOKIE</tracking-mode>
</session-config>

Set session timeout to match your BlackBerry UEM policy. Cookie-only tracking avoids URL rewriting issues with BlackBerry browsers.

Handling Push Service Integration

BlackBerry Push Service maintains persistent connections. These connections bind to specific application servers. When a push arrives, the server must have the user session locally.

Configure sticky sessions at your load balancer. Use the JSESSIONID cookie for affinity. Set a long timeout, at least 4 hours, to match BlackBerry push connection lifetimes.

If you cannot use sticky sessions, implement a push redirect mechanism. Store the current server mapping in Terracotta shared map. When push arrives at wrong server, forward internally via cluster RPC.

Starting and Validating the Cluster

Starting Terracotta Servers in Order

Start the active server first. Wait for full startup before starting the passive. Check logs for these messages:

INFO  [Terracotta Server] Server started on 10.0.1.10:9510
INFO  [HA] State changed to ACTIVE-COORDINATOR

Then start the second server. It should show:

INFO  [HA] State changed to PASSIVE-STANDBY
INFO  [HA] Connected to active coordinator at 10.0.1.10:9530

Use the start-tc-server.sh script with your config:

/opt/terracotta/current/bin/start-tc-server.sh -f /opt/terracotta/config/tc-config.xml

Verifying Cluster Formation

Run the cluster health check tool:

/opt/terracotta/current/bin/tc-cluster-admin.sh -h localhost -p 9510 status

Output should show both servers with HEALTHY status. The active server shows COORDINATOR role. The passive shows STANDBY.

Check the Management Console at http://tsa1:9540/tmc. Log in with admin credentials. The dashboard shows cluster topology, connected clients, and memory usage.

Connecting Application Servers

Start one application server. Watch the Terracotta server logs for client connection:

INFO  [Client Connection] Client connected from 10.0.1.20:54321
INFO  [Client Registration] Registered client: tomcat-node1

Verify in the Management Console. The Clients tab should show your application server with session count and memory usage.

Testing Session Replication

Create a simple test servlet that writes to session and reads back. Deploy to both application servers. Access through load balancer. Refresh repeatedly. The session ID should stay constant. The counter should increment across servers.

Then kill one application server. Refresh. The session should continue on the remaining server without data loss. This validates the complete stack.

Performance Tuning for Mobile Traffic

Cache Configuration for BlackBerry Data Patterns

BlackBerry applications exhibit bursty access patterns. Users check email in batches. Push notifications trigger simultaneous requests. Configure caches to handle bursts without evicting hot data.

<cache name="blackberry-sessions">
  <max-entries>100000</max-entries>
  <eviction-policy>LRU</eviction-policy>
  <time-to-live>1800</time-to-live>
  <time-to-idle>900</time-to-idle>
</cache>

Set TTL to match your session timeout. TTI at half TTL handles users who background the app briefly.

Off-Heap Sizing for Session Data

Monitor off-heap usage in the Management Console. Set alerts at 70% utilization. Session data grows with user count and feature additions. Plan capacity for peak plus 50%.

Use the Terracotta sizing spreadsheet. Input your session attribute count, average size, and concurrent users. It calculates required off-heap per node.

Network Buffer Tuning

Mobile networks have higher latency and packet loss. Increase socket buffers to absorb bursts:

<network>
  <send-buffer-size>1048576</send-buffer-size>
  <receive-buffer-size>1048576</receive-buffer-size>
  <socket-timeout>30000</socket-timeout>
</network>

1 MB buffers handle typical mobile latency variations. 30 second socket timeout accommodates slow handovers.

Garbage Collection Optimization

Terracotta servers run with large heaps. GC pauses can trigger false failure detection. Tune G1GC for your workload:

-XX:G1HeapRegionSize=16m
-XX:InitiatingHeapOccupancyPercent=45
-XX:ParallelGCThreads=4
-XX:ConcGCThreads=2

Test with production-like load. Measure pause times. Adjust until 99th percentile stays under 200ms.

Monitoring and Maintenance

Key Metrics to Watch

Set up monitoring for these critical metrics. Use Prometheus, Datadog, or your existing monitoring stack.

• Cluster health: All nodes HEALTHY, no split-brain
• Client count: Matches expected application servers
• Off-heap usage: Below 70% on all nodes
• Disk usage: Below 80% on data volumes
• Replication latency: Under 10ms p99
• Failover count: Zero in normal operation

Log Analysis for Common Issues

Terracotta logs are verbose but structured. Look for these patterns:

• Client reconnect storms: Many reconnects in short time indicates network instability
• Split-brain warnings: Immediate action required, data divergence detected
• Slow replication: Latency spikes suggest GC pressure or network congestion
• Out of memory: Off-heap exhaustion, increase allocation or reduce session size

Use log aggregation. Search across all nodes simultaneously during incidents.

Backup and Disaster Recovery

Terracotta data is recoverable from disk tier. Schedule daily backups of the data directory. Use filesystem snapshots if available. Test restore quarterly.

Document the recovery procedure. Include steps for: single node failure, full cluster restart, and data corruption scenarios. Practice in staging.

Rolling Upgrades

Terracotta supports rolling upgrades within minor versions. Upgrade passive server first. Promote to active. Upgrade former active. Never skip minor versions. Read release notes for breaking changes.

Schedule upgrades during low-traffic windows. BlackBerry traffic often dips overnight. Allow 30 minutes per node for startup and state transfer.

Troubleshooting Common BlackBerry Integration Issues

Session Loss After Network Handover

Users report logout when switching from Wi-Fi to cellular. This usually means the load balancer routed to a server without the session. Verify sticky session configuration. Check that JSESSIONID cookie persists across network changes.

Test by simulating handover. Use two networks. Monitor which server handles each request. The same server should handle all requests for a session.

Push Notifications Delivered to Wrong Server

Push arrives but user does not receive it. The push server contacted an application server that does not have the user session. Implement the redirect mechanism described earlier. Store server affinity in a Terracotta shared map keyed by user ID.

High Memory Usage on Application Servers

Terracotta client library caches recently accessed objects locally. Large session objects cause heap pressure. Configure client-side cache limits:

-Dtc.client.cache.size=512m
-Dtc.client.cache.ttl=300

Monitor application server heap. Adjust based on actual usage patterns.

Cluster Split-Brain After Network Partition

Network glitch isolates servers. Both think they are active. Data diverges. Terracotta detects this on reconnect and shuts down one node. Check logs for “split-brain detected” messages.

Prevent by using dedicated cluster network. Configure multiple network paths. Use the networked-active-passive HA mode with proper quorum settings.

Advanced Configuration for Scale

Multi-Data Center Deployment

For disaster recovery, extend cluster across data centers. Use asynchronous replication for the remote site. Latency must stay under 50ms for synchronous. Most cross-DC links exceed this.

Configure a passive mirror group in the remote DC. It receives updates asynchronously. On primary DC failure, promote remote group manually. This avoids split-brain from network partitions.

Striping for Very Large Clusters

Beyond 10 application servers, consider striping. Divide sessions across multiple Terracotta server arrays. Each stripe handles a subset of users. Route based on session ID hash.

This adds complexity. Only implement when single array hits limits. Most BlackBerry deployments never need this.

Custom Data Structures for BlackBerry Features

BlackBerry UEM APIs return complex objects. Device info, policy compliance, app inventory. Store these in Terracotta shared maps with custom serialization. Register serializers in tc-config.xml:

<serialization>
  <serializer class="com.company.blackberry.DeviceInfoSerializer">
    <for-class>com.company.blackberry.DeviceInfo</for-class>
  </serializer>
</serialization>

Custom serializers reduce payload size and improve replication speed.

Conclusion

You now have a complete roadmap for setting up Terracotta for BlackBerry. We covered environment preparation, installation, configuration, integration, validation, tuning, monitoring, and troubleshooting. Each step builds on the previous one. Skip nothing.

Start with a two-node cluster in staging. Validate every scenario: normal operation, node failure, network partition, rolling upgrade. Document your specific configuration. Create runbooks for common operations.

Remember that BlackBerry traffic patterns differ from web traffic. Bursty. Intermittent. Push-driven. Tune for these patterns. Monitor relentlessly. The effort pays off in user satisfaction and reduced support load.

Your users will not notice Terracotta. They will only notice that things work. That is the goal. Invisible infrastructure enabling reliable mobile experiences.

Frequently Asked Questions

Can Terracotta cluster BlackBerry applications running on different application servers?

Yes, Terracotta supports heterogeneous clusters. You can cluster WebLogic, Tomcat, and JBoss nodes together as long as they run compatible Java versions and use the same Terracotta client library version.

Does Terracotta require code changes to my BlackBerry application?

No, Terracotta works through bytecode instrumentation at JVM startup. Your application code remains unchanged. You only need to add the Terracotta javaagent and configure session replication in your web.xml and context.xml files.

How does Terracotta handle BlackBerry device network handovers between Wi-Fi and cellular?

Terracotta maintains session state across all clustered servers. When a network handover routes requests to a different server, that server already has the current session data. The user experiences no interruption.

What happens to sessions during a Terracotta server failover?

During failover, the passive server becomes active within seconds. Application servers reconnect automatically using the configured reconnect window. Sessions remain intact because data is mirrored synchronously between active and passive servers.

Can I use Terracotta with BlackBerry UEM Cloud deployments?

Terracotta clusters your custom BlackBerry applications, not the UEM Cloud service itself. If you host applications on-premises or in your own cloud that integrate with UEM Cloud, Terracotta can cluster those application servers.

How do I monitor Terracotta cluster health in production?

Use the Terracotta Management Console at port 9540 for real-time monitoring. Integrate with your monitoring stack via JMX metrics. Key metrics include cluster health status, connected client count, off-heap memory usage, replication latency, and failover events.