Mappings & Class Resolution

Understanding module mappings, class resolution, and the @moduleName notation

Every BoxLang module receives automatic mappings for class resolution and optional web access. Understanding these mappings is essential for importing classes and serving web content.

Internal Module Mapping

When a module is registered, BoxLang creates an internal mapping for class resolution:

Property	Value	Purpose
Path	bxModules.{moduleName}	Internal class path prefix
Physical	Module root directory	Where classes/BIFs/components live
Web Access	❌ No	Only for class resolution

For a module named myModule, the internal mapping bxModules.myModule points to the module root. This is used for class resolution only — it's not web-accessible.

Public Web Mapping

For serving static files via HTTP, BoxLang creates a public mapping:

Property	Default	Customizable
Folder	{moduleRoot}/public/	✅ this.publicMapping
URL Path	/bxModules/{name}/public/	✅ Override mapping name

Files in myModule/public/css/style.css are accessible at:

http://yourserver.com/bxModules/myModule/public/css/style.css

Customizing Mappings

Override defaults in your module descriptor:

ModuleConfig.bx

class {
    // Override internal mapping name
    this.mapping = "customName";

    // Override public folder
    this.publicMapping = {
        name: "assets",           // URL: /bxModules/customName/assets/
        path: "web/static",       // Physical path relative to module root
        external: false           // true = absolute path
    };
}

Java @BoxModule

The @moduleName Notation

BoxLang provides a powerful syntax for explicitly addressing classes from specific modules using the @moduleName suffix. This improves performance and eliminates ambiguity.

Why Use @moduleName?

Without @moduleName:

import models.UserService

• BoxLang searches ALL modules
• Slower with many modules loaded
• Ambiguous if duplicates exist

With @moduleName:

import models.UserService@myModule

• Direct lookup in the specified module
• Faster resolution
• No ambiguity

Importing BoxLang Classes

// Import from a specific module
import models.ActiveEntity@cborm
entity = new ActiveEntity()

// Import with alias
import models.ActiveEntity@cborm as AE
entity = new AE()

// Import component
import components.DataTable@bx-ui-forms
table = new DataTable()

Importing Java Classes from Modules

The same notation works for Java classes packaged in modules:

// Import Java class from module
import org.owasp.esapi.ESAPI@bx-esapi
encoder = ESAPI.encoder()

// Import with alias
import org.owasp.esapi.ESAPI@bx-esapi as SecurityAPI
encoder = SecurityAPI.encoder()

// Create instance directly
encoder = new java:org.owasp.esapi.reference.DefaultEncoder@bx-esapi()

Using createObject()

// Create BoxLang class from a module
service = createObject( "component", "models.UserService@myModule" )

// Create Java class from a module
driver = createObject( "java", "com.mysql.cj.jdbc.Driver@bx-mysql" )

The @moduleName notation requires the module to be loaded and activated. If the module isn't loaded, you'll get a class-not-found error.

Class Loading Hierarchy

When resolving a class with @moduleName, BoxLang searches:

1. Module's compiled classes (modules.{moduleName} package prefix)
2. Module's libs/ folder (JAR dependencies)
3. Parent class loader (runtime classes — fallback)

This isolation ensures modules don't interfere with each other's dependencies.

Custom Class Resolvers

Modules can register custom class resolvers with unique prefixes (extending the built-in bx: and java: resolvers). See Advanced Collaboration for details.

Best Practices

1

Use @moduleName for Clarity

Always use @moduleName when importing classes from modules to avoid ambiguity and improve performance.

✅ import models.UserService@myModule ❌ import models.UserService

2

Keep Public Folders Organized

Structure your public/ folder logically:

public/
├── css/
├── js/
├── images/
└── templates/

3

Document Your Mappings

In your module's README, document what mappings are created and how to import your classes.

Next Steps

• Configuration — Module settings and runtime overrides
• Advanced Collaboration — System settings providers and class resolvers
• Capabilities — BIFs, components, services, and more