Eclipse Java Access Restrictions: QName and rt.jar

This page explains Eclipse access restrictions, Java execution environments, and why a public class such as QName can be reported as unavailable. You will learn how to distinguish a compiler configuration problem from a genuine Java-version compatibility problem and choose an appropriate fix.

rt.jar was the core Java runtime archive in older JDK releases. It contained standard Java platform classes such as String, collections, I/O classes, and XML APIs.

An Eclipse access restriction is not necessarily Java saying that a class is private or missing. Eclipse can attach access rules to a library. These rules intentionally hide packages or classes that are not part of the Java platform level your project claims to support.

javax.xml.namespace.QName is a standard Java API in Java 5 and later. It is marked Since: 1.5 in its API documentation. Therefore, a project configured for a Java 1.4 execution environment may treat QName as forbidden—even if Eclipse is physically using a Java 5 rt.jar file.

This commonly occurs when Eclipse uses a newer installed JDK to compile code while applying an older execution environment's API rules. The newer JDK contains more classes, but the rules prevent your code from accidentally depending on APIs unavailable on the older target runtime.

This matters because compiler success alone does not guarantee deployment success. If code is meant to run on Java 1.4, it must not rely on Java 5-only platform classes unless the required API is separately supplied and compatible on that runtime.

Think of the installed JDK as a large library building and the project's execution environment as a visitor pass.

A Java 5 rt.jar gives Eclipse access to the whole building, including the QName book. But a Java 1.4 visitor pass says, “Only use books that existed in Java 1.4.” Eclipse sees that the book is physically present but blocks it because the pass does not permit it.

The error is therefore often saying “this API is outside your declared compatibility boundary”, not “the class does not exist.”

QName represents an XML qualified name: a local name together with an optional namespace URI and prefix.

import javax.xml.namespace.QName;

public class QNameExample {
    public static void main(String[] args) {
        QName customerElement = new QName(
            "https://example.com/customer",
            "customer",
            "c"
        );

        System.out.println(customerElement.getNamespaceURI());
        System.out.println(customerElement.getLocalPart());
        System.out.println(customerElement);
    }
}

The code creates the XML name c:customer in the namespace https://example.com/customer.

For this code to compile without a restriction, the project must use an execution environment that includes QName, such as Java 5 or later. If your application must run on Java 1.4, you need to use the XML/WSDL stack intended for that runtime and ensure its API dependencies are present.

Consider this project setup:

Installed JDK: Java 5
Project execution environment: J2SE-1.4
Code imports: javax.xml.namespace.QName

What Eclipse does:

1. Eclipse reads the project's configured execution environment: J2SE-1.4.
2. It loads the Java 5 system library because that is the JDK installed or selected for the project.
3. It applies access rules representing the Java 1.4 API surface.
4. The compiler resolves QName in Java 5's rt.jar.
5. Eclipse recognizes that QName was introduced in Java 5, not Java 1.4.
6. Eclipse reports an access restriction instead of allowing a Java 5-only dependency into a Java 1.4-targeted project.

The key detail is that the JDK used to compile and the Java version the project promises to support can be different.

Access rules and execution environments are useful whenever code must run on a specific platform version.

• Legacy enterprise applications: A team may keep a service compatible with an older JRE while developers use newer JDK installations.
• SDK development: A library may promise compatibility with a particular Java version and must avoid newer APIs.
• XML and SOAP clients: Generated WSDL stubs often depend on a specific generation tool and XML/JAX-RPC/JAX-WS API version.
• CI builds: A build server can enforce the intended Java API level so developers do not accidentally use unsupported classes.
• Migration projects: Teams can identify Java-version dependencies before moving an application from Java 1.4 to Java 5 or later.

In real projects, developers usually make the runtime target explicit rather than manually adding random JAR files.

Common practices include:

• Match the execution environment to deployment. If production runs Java 5, configure the Eclipse project to use a Java 5 execution environment and compiler compliance level.
• Use a real Java 1.4 runtime when Java 1.4 support is required. This is more reliable than compiling against a newer rt.jar with restrictions.
• Keep generated sources reproducible. Store the WSDL and the generator version/options, then regenerate stubs when changing the SOAP/XML stack.
• Avoid overriding platform classes casually. Adding a JAR that contains a class with the same fully qualified name as a JDK class can lead to class-loading surprises.
• Validate runtime dependencies. Generated SOAP clients may need more than the generated source files: they can require matching XML, SOAP, and RPC implementation libraries.

For the original situation, regenerating stubs is not automatically required. First determine the intended runtime:

• If the application is now intended to run on Java 5, configure Eclipse for Java 5. Existing generated source may compile and work if its supporting libraries are compatible.
• If it must still run on Java 1.4, use a Java 1.4-compatible toolchain and dependencies. Regenerating with the appropriate old generator may be the cleanest option when the current stubs require Java 5 APIs.

Assuming “the JAR is present” means the API is allowed

A class can be physically present in a library but blocked by Eclipse access rules.

import javax.xml.namespace.QName; // May be restricted in a J2SE-1.4 project

Check the project's execution environment and compiler compliance settings, not only the Build Path list.

Changing only the compiler compliance level

Changing source compliance from 1.4 to 1.5 may not be enough if the project's JRE system library or execution environment remains configured as Java 1.4. Align all relevant settings.

Adding another JAR that also contains QName

Trying to fix the problem by adding an XML API JAR can create duplicate classes with the same package and name.

javax.xml.namespace.QName

On Java 5, the bootstrap class loader normally loads JDK classes before ordinary application JARs. The additional JAR may not be used as expected.

Removing access rules without understanding the target

Removing or weakening a restriction can make Eclipse compile the code, but the application may then fail on the older Java runtime with ClassNotFoundException or other linkage errors.

Treating generated code as version-independent

Generated source is tied to the generator, the WSDL, and the API/runtime libraries available at generation time. Keep those versions documented.

• Access restriction: An Eclipse rule that blocks use of selected classes or packages.
• rt.jar: The core Java runtime archive used by older JDKs; it existed before Java 9.
• QName: javax.xml.namespace.QName, a standard Java API available from Java 5 onward.
• A newer JDK can be installed while a project is configured to target an older Java API level.
• If Eclipse says a class in rt.jar is restricted, inspect the project's Execution Environment, JRE System Library, and Compiler compliance level.
• Target Java 5+ when deploying on Java 5+ and using QName from the JDK.
• Target Java 1.4 only when you have a Java 1.4-compatible runtime, libraries, and generated stubs.
• Do not add duplicate platform API JARs as a first response to an access-restriction error.
• Regenerate WSDL stubs when changing to an incompatible SOAP/XML toolchain or when you need a reproducible, supported dependency set.

Why is a public Java class reported as inaccessible in Eclipse?

Eclipse access rules can restrict a public class when it is outside the API level configured for the project. Public visibility and Eclipse API eligibility are separate checks.

Is QName included in Java 1.4?

javax.xml.namespace.QName became part of the standard Java platform in Java 5. Java 1.4 applications may obtain similar APIs through compatible external XML libraries, depending on their stack.

Does this error mean that rt.jar is broken?

No. It usually means the project is using a Java 5 rt.jar while Eclipse is enforcing Java 1.4 compatibility rules.

Should I remove the access restriction in Eclipse?

Only if the application will actually run on a runtime that provides the API. Removing the warning without changing the deployment target can hide a real compatibility problem.

Should I regenerate the WSDL stubs?

Not necessarily. If you are moving the application to Java 5 and the existing generated code and libraries are compatible, changing project configuration may be enough. Regenerate when the stubs require a different or incompatible SOAP/XML runtime, or when you want a supported reproducible generation process.

Why does adding a JAR not always fix an XML class problem?

Java class loading gives core platform classes special priority. A JAR that duplicates classes already supplied by the JDK may be ignored or cause version conflicts.

What should match in an old Java project?

The deployment JRE, Eclipse execution environment, compiler configuration, generated stubs, and SOAP/XML runtime dependencies should all be compatible with one another.

• Java execution environments — Define the standard API level a project is allowed to use.
• Java compiler compliance level — Controls language features and generated bytecode compatibility.
• Eclipse build path and access rules — Explains how Eclipse resolves and restricts libraries.
• Java class loading — Helps explain why duplicate classes in JAR files can be problematic.
• JAR dependencies — Covers how applications receive non-platform libraries.
• WSDL code generation — Generated SOAP client code depends on generator and runtime versions.
• Java API compatibility — Helps plan upgrades while preserving deployment support.
• XML namespaces and QName — Explains the XML concept represented by QName.