Package Renamer Tool (TCE 8.0) - Admin Guide

Last updated
Save as PDF

Overview

The Package Renamer Tool helps you resolve required package name changes when upgrading to TeamConnect 8.0. The upgrade to Oracle JDK 21 introduces name changes (for example, from javax.* to jakarta.*). This tool automates these changes to ensure your customizations remain compatible.

Note: The Package Renamer tool runs automatically during EXE installation. If you are using the CLI (Command Line Installer) installer or performing a manual installation, you must run the tool separately.

Why is this important

TeamConnect 8.0 requires Oracle JDK 21. As part of this change, some Java packages have moved from javax.* to jakarta.*. Automating these updates reduces the effort and risk during your upgrade.

What the tool does

Apply package-name changes to compiled .class files in a local working directory (Method 1).
Apply package‑name changes to references stored by TeamConnect (Method 2) using a database connection you provide.
Keep the mapping logic in a simple, version‑controlled packagerenamer.properties file.

Note: Always run in non‑production first and take backups. See the Safety checklist below.

Audience and Prerequisites

Who this guide is for

This guide is for system administrators, developers, or service partners who are responsible for upgrading TeamConnect and maintaining customizations.

Before you begin

You have the Package Renamer Tool, which is included with your TeamConnect 8.0 installation files.
Java is installed on the computer where you will run the tool.
You have access to your non-production TeamConnect environment and database.
You understand your organization’s change control process, including backups and approvals.

Safety checklist

Always create a working copy of any files before you run the tool. Never edit your only copy.
You must back up your TeamConnect database before you use Method 2.
Always run the tool and validate the results in a non-production environment before deploying to production.
Use database credentials with the minimum required permissions (update-only rights, if possible).

How the Tool Works

You define the find-and-replace rules in the packagerenamer.properties file. Each line in the file maps an old package string to the new package string.
- For example: javax.servlet=jakarta.servlet
The tool reads this configuration file and applies the changes to either:
- to compiled classes in a local directory (Method 1), or
- to database‑stored references in TeamConnect (Method 2) using connection details from upgrade.properties.

Recommendation:

Use specific mappings (e.g., javax.servlet=jakarta.servlet, javax.ws.rs, etc.).
Carefully use catch-alls (e.g., javax.jakarta) to avoid unintended changes.

Choose a Method

Method	Use when...	Inputs	Output
Method-1: Directory-based	You have compiled `.class` files from custom code available on your local disk.	A working directory that contains your copied `.class` files and the packagerenamer.properties file.	The `.class` files in your working directory are updated (operate on the working copy).
Method-2: TeamConnect Integration	The references that must change are stored in TeamConnect and exposed via the application.	The upgrade.properties with database connection details (and an encrypted password), plus `packagerenamer.properties` file.	Changes are applied directly to the target database (run against a non‑production environment first).

Scripts vs. direct JAR: Your distribution may include OS‑specific scripts (e.g., upgrade.bat for Windows or upgrade.sh for macOS/Linux).

Method 1: Directory-Based (Update Local Files)

Goal: Apply your package mappings to a directory of compiled .class files that you have copied to a safe working folder.

Step 1: Configure mappings in `packagerenamer.properties`

Use the starter template provided in the Appendix as a base. Add or adjust the lines for the specific packages your customizations use.

Note: The javax=jakarta mapping is added to the packagerenamer.properties file by default. In this case, you only need to add other custom mappings if required.

Example (excerpt):

# --- Blanket rules (use with caution) ---

# These are broad rules that will rename any package starting with the specified prefix.

# Use with caution and validate thoroughly in non‑prod.

javax=jakarta

# Jakarta transitions (examples — keep specific)

javax.servlet=jakarta.servlet
javax.ws.rs=jakarta.ws.rs
javax.xml.bind=jakarta.xml.bind

# Historic TopLink → EclipseLink (as seen in legacy customizations)

oracle/toplink/publicinterface=org/eclipse/persistence/sessions
oracle/toplink/threetier=org/eclipse/persistence/sessions/server
oracle/toplink/queryframework=org/eclipse/persistence/queries
oracle/toplink/changesets=org/eclipse/persistence/sessions/changesets
oracle/toplink=org/eclipse/persistence

Step 2: Run the tool

From your working directory, run the appropriate command:

Windows (if a script is provided):

    upgrade.bat

macOS/Linux (if a script is provided):

    chmod +x upgrade.sh

    ./upgrade.sh

Optional: Process a single file for testing

To test your mapping rules on a single file, you can use the following command.

Place the single .class file in the same folder as the upgrade tool.
Run the command, replacing <filename> with the name of your file:

    Upgrade -Dfile=<filename>

Note: This will only recompile the single specified file.

Important: Ensure the upgrade.properties file has no database details before running this command.

Optional: Process multiple files with a batch file

To automate processing for a large number of files, you can use a batch file.

In your working directory, create a subfolder named Class Files.
Place all the .class files you want to update into the Class Files folder.
Create a new file in your working directory, save it as .bat file, and add the following content:

    @echo off
    setlocal
    
    for %%a in ("Class Files\*.class") do (
        echo Processing file: %%a
        call upgrade.bat -Dfile="%%a"
    )
    
    endlocal
    echo Done.
    pause

Run the .bat file to process all .class files.

Step 3: Verify results

Review the tool’s console output / logs for a success message and counts.
Optionally decompile a sample of updated classes with an offline, internal decompiler to verify imports changed as expected.
Deploy to a non‑production TeamConnect and test the features that depend on the updated classes.

Method 2: TeamConnect Integration (Update Database References)

Goal: Apply your package mappings to references stored in TeamConnect via a database connection.

Step 1: Configure the database connection in `upgrade.properties`

Use the starter template provided in the Appendix as a base and set values for your environment.

Important: You must encrypt your database password before adding it to the upgrade.properties file.

# Required

db.product=Oracle          # or SQLServer
db.username=TC_APP
db.password=<ENCRYPTED_STRING>

# Server/DB examples

# Oracle (SERVICE-based JDBC)

db.server=ora-host:1521/TCDBSERVICE

# SQL Server

db.server=sql-host,1433
db.databaseName=TeamConnectDB    # SQL Server only

Encrypt the password

Locate the encrypt.jar file, which is included with TeamConnect utilities.
Run this command to generate the encrypted string:

    java -jar encrypt.jar <YourPlaintextPassword>

Copy the encrypted output and paste it into the db.password value in your upgrade.properties file.

Step 2: Configure mappings in `packagerenamer.properties`

Use the same approach as in Method 1. Keep mappings specific (carefully use javax=jakarta catch‑alls if needed).

Note: The javax=jakarta mapping is added to the packagerenamer.properties file by default. In this case, you only need to add other custom mappings if required.

Step 3: Run the tool

Run the operating system specific script if provided (upgrade.bat/upgrade.sh)

Step 4: Verify results

Confirm the success message and updated counts in the console/logs.
Log in to non‑production TeamConnect and validate the affected features.
If your organization requires it, compare a pre/post snapshot (e.g., export of configuration or UI behavior) to document the change.

Optional: Updating .java Source Files with PowerShell

For developers who need to update the original .java source files, the following PowerShell script can be used to replace javax import statements with jakarta.

Imporant: This script directly modifies source files. Always run it on a project with a clean version control status (e.g., after committing all changes in Git) and in a non-production environment first.

PowerShell Batch Replace:

Open PowerShell.
Navigate to the root directory of your source code repository.
Run the following script. You can change the value of the $root variable if your source code is not in a src folder.

# Bulk replace import lines from javax.* to jakarta.* under a source tree.

# Run at repo root AFTER committing a clean state.

$root = "src"
Get-ChildItem -Path $root -Recurse -Include *.java |
  ForEach-Object {
    (Get-Content $_.FullName) |
      ForEach-Object {
        if ($_ -match '^\s*import\s+javax\.') {
          $_ -replace '^\s*import\s+javax\.', 'import jakarta.'
        } else {
          $_
        }
      } | Set-Content $_.FullName -Encoding UTF8
   }

# Optional: show changed files if you are using Git

git diff --name-only

Package Renamer Tool Scan Areas

The following is a list of all areas scanned by the package renamer tool:

Root/System/Object Definitions/Account/Rules/Automated Actions
Root/System/Object Definitions/Account/Rules/Automated Qualifiers
Root/System/Object Definitions/Account/Rules/Legacy Rules
Root/System/Object Definitions/Account/Screens
Root/System/Object Definitions/Appointment/Rules/Automated Actions
Root/System/Object Definitions/Appointment/Rules/Automated Qualifiers
Root/System/Object Definitions/Appointment/Rules/Legacy Rules
Root/System/Object Definitions/Appointment/Screens
Root/System/Object Definitions/Contact/Rules/Automated Actions
Root/System/Object Definitions/Contact/Rules/Automated Qualifiers
Root/System/Object Definitions/Contact/Rules/Legacy Rules
Root/System/Object Definitions/Contact/Screens
Root/System/Object Definitions/Custom Object/Rules/Automated Actions
Root/System/Object Definitions/Custom Object/Rules/Automated Qualifiers
Root/System/Object Definitions/Custom Object/Rules/Legacy Rules
Root/System/Object Definitions/Custom Object/Screens
Root/System/Object Definitions/Document/Rules/Automated Actions
Root/System/Object Definitions/Document/Rules/Automated Qualifiers
Root/System/Object Definitions/Document/Rules/Legacy Rules
Root/System/Object Definitions/Document/Screens
Root/System/Object Definitions/Expense/Rules/Automated Actions
Root/System/Object Definitions/Expense/Rules/Automated Qualifiers
Root/System/Object Definitions/Expense/Rules/Legacy Rules
Root/System/Object Definitions/Expense/Screens
Root/System/Object Definitions/Group/Rules/Automated Actions
Root/System/Object Definitions/Group/Rules/Automated Qualifiers
Root/System/Object Definitions/Group/Rules/Legacy Rules
Root/System/Object Definitions/Group/Screens
Root/System/Object Definitions/History/Rules/Automated Actions
Root/System/Object Definitions/History/Rules/Automated Qualifiers
Root/System/Object Definitions/History/Rules/Legacy Rules
Root/System/Object Definitions/History/Screens
Root/System/Object Definitions/Invoice/Rules/Automated Actions
Root/System/Object Definitions/Invoice/Rules/Automated Qualifiers
Root/System/Object Definitions/Invoice/Rules/Legacy Rules
Root/System/Object Definitions/Invoice/Screens
Root/System/Object Definitions/Line Item/Rules/Automated Actions
Root/System/Object Definitions/Line Item/Rules/Automated Qualifiers
Root/System/Object Definitions/Line Item/Screens
Root/System/Object Definitions/PIFL Object/Rules/Automated Actions
Root/System/Object Definitions/PIFL Object/Rules/Automated Qualifiers
Root/System/Object Definitions/PIFL Object/Rules/Legacy Rules
Root/System/Object Definitions/PIFL Object/Screens
Root/System/Object Definitions/SPD4 Object/Rules/Automated Actions
Root/System/Object Definitions/SPD4 Object/Rules/Automated Qualifiers
Root/System/Object Definitions/SPD4 Object/Rules/Legacy Rules
Root/System/Object Definitions/SPD4 Object/Screens
Root/System/Object Definitions/Security Rights Audit/Rules/Automated Actions
Root/System/Object Definitions/Security Rights Audit/Rules/Automated Qualifiers
Root/System/Object Definitions/Security Rights Audit/Rules/Legacy Rules
Root/System/Object Definitions/Security Rights Audit/Screens
Root/System/Object Definitions/Security Rights Audit Report Wizard/Rules/Automated Actions
Root/System/Object Definitions/Security Rights Audit Report Wizard/Rules/Automated Qualifiers
Root/System/Object Definitions/Security Rights Audit Report Wizard/Rules/Legacy Rules
Root/System/Object Definitions/Security Rights Audit Report Wizard/Screens
Root/System/Object Definitions/Task/Rules/Automated Actions
Root/System/Object Definitions/Task/Rules/Automated Qualifiers
Root/System/Object Definitions/Task/Rules/Legacy Rules
Root/System/Object Definitions/Task/Screens
Root/System/Object Definitions/User/Rules/Automated Actions
Root/System/Object Definitions/User/Rules/Automated Qualifiers
Root/System/Object Definitions/User/Rules/Legacy Rules
Root/System/Object Definitions/User/Screens
Root/System/Custom Rules
Root/System/Legacy Rules
Root/System/Tools
Root/System/Logging
Root/System/Portal
Root/System/StartUp
Root/System/Scheduled Actions
Root/System/Libraries

Important: If you add any third-party JAR files to the library folder, they will also be affected by the Package Renamer Tool. To avoid potential issues, make sure to update those JAR files manually or create backups before running the tool.

Troubleshooting

Symptom / Problem	Possible cause	How to fix / Solution
Authentication fails when running Method 2	Wrong database user, wrong server string, or password not encrypted.	Verify db.username, db.server, and regenerate the encrypted password with encrypt.jar; test connectivity with a simple JDBC client if possible.
Tool runs but reports 0 changes	Mappings do not match actual package strings; blanket rules skipped targets.	Use specific mappings. Check your files to confirm that the old package names you are trying to replace actually exist.
“Permission denied” or file write errors	Your working directory is in a protected or read-only location.	Ensure your working directory is in a location where you have write permissions and try again.
Script won’t run on macOS/Linux	Windows `.bat` cannot execute on Unix‑like systems.	Use `upgrade.sh` if provided, or run the JAR directly with `java -jar ...`
App behavior changed unexpectedly	A broad mapping rule (like `javax=jakarta`) modified unintended strings.	Restore your files or database from the backup you created. Change your mapping rules to be more specific, then re-run and re-test in your non-production environment.

Validation and Rollback

Validation: After running the tool, perform complete functional smoke tests on all areas of your application that rely on the updated packages; review system logs for any warnings.
Rollback: To undo the changes, either restore your working files from your copy (Method 1) or restore the database from the backup / snapshot you created (Method 2).

Appendix: Starter Templates

This guide includes two downloadable starter templates:

packagerenamer.properties – Contains example mappings (Jakarta + common legacy TopLink → EclipseLink).
upgrade.properties – Database connection properties with encrypted password placeholder.