Package import establishes a dependency that allows elements in one package to reference elements in another based on their namespace. In contrast, package merge combines two separate package definitions into a single unified structure, resolving namespace collisions and merging classifiers without creating direct usage dependencies.

Core Conceptual Distinctions

Understanding the fundamental difference between these two mechanisms is essential for large-scale system design. The choice between them dictates how your model behaves when scaled. One creates a relationship for usage, while the other unifies structure.

Definition of Package Import

Package import acts as a mechanism to expose elements from a source package to a target package. It functions similarly to an import statement in Java or Python. When package A imports package B, elements inside package A can see and reference public elements from package B.

This action does not change the internal structure of the source package. It merely makes specific definitions available in a new context. It creates a directed relationship where the importing package relies on the imported one.

• Creates a usage dependency relationship.
• Allows access to public and protected elements.
• Does not merge classifiers or resolve name conflicts automatically.
• Typically used to reduce coupling and organize namespaces.

Definition of Package Merge

Package merge is a structural operation designed to combine the contents of two packages into one. It is often used when modularization efforts require merging distinct model views into a single canonical model. The result is a single package containing all elements from both sources.

This process is critical when multiple stakeholders have modeled different aspects of the same domain. Package merge allows them to integrate their work without manual copying of elements. It handles the reconciliation of overlapping definitions.

• Unifies the namespace of the involved packages.
• Resolves collisions based on the merge strategy.
• Does not create a dependency for external usage.
• Used for integrating partial models into a complete model.

Visibility vs. Inheritance Semantics

The choice between import and merge fundamentally changes how visibility and inheritance are handled within your system architecture. This distinction determines which classes can see other classes and how they interact.

Import Handles Visibility

When you import a package, you are essentially opening a window to look at it. The visibility rules of the original package still apply, but the target package gains permission to see them. Public elements become accessible to the importers.

However, this visibility is strictly about reference. It does not change the implementation of the classes. If a class in the source package is private, it remains private even if the target package imports the source. The import acts as a visibility modifier for the target namespace only.

This is crucial for managing dependencies. You should use package import when you need to access functionality from a library without altering its internal structure or merging it into your own model.

Merge Alters Structure and Inheritance

Package merge changes the very identity of the classes involved. When two packages are merged, the classifiers within them become part of the same namespace. This allows for more complex interactions that require a unified view.

Inheritance logic changes because the merged package is treated as a single entity. If a class in the first package extends a class in the second package, the relationship is direct. There is no dependency edge required to traverse the namespace boundary.

Use case: Merging is ideal for integrating model parts created by different teams into a single executable model. It ensures that all inheritance hierarchies are correctly resolved within one namespace.

Scenario Analysis: Real-World Application

To truly grasp the difference, consider a real-world scenario involving a large software system. Imagine a project with a “Core” package and a “UserInterface” package.

Scenario 1: Importing a Library

You are building a UI module that needs to use data structures defined in a Core module. You do not need to modify the Core module. You simply need to access its public methods.

In this case, you use package import. The UI package imports the Core package. This creates a dependency arrow pointing from UI to Core. If the Core package changes, the UI package knows it depends on it.

If you were to use package merge here, you would be forcing the Core definitions into the UI namespace. This creates a structural mess. It would imply that the Core classes are now part of the UI model, which is semantically incorrect.

Import preserves the independence of the Core module while allowing usage. This is the standard approach for library management and dependency injection.

Scenario 2: Merging Model Views

Consider a scenario where a database team creates a “DataAccess” package and an application team creates an “ApplicationLogic” package. Both packages define a “User” class because they model the same entity from different perspectives.

You need to combine these into a single, coherent model for the final design. You use package merge. The tool attempts to reconcile the two “User” definitions.

If the definitions conflict, the merge operation might require manual intervention to resolve which attributes take precedence. The result is a single “User” class that contains attributes from both teams. This is not a dependency; it is a consolidation.

This structure is vital for managing complex enterprise systems where multiple views of the same data must coexist and eventually converge.

Common Confusion Points

Users often confuse these two concepts because both involve multiple packages. However, the intent and the result are fundamentally different. Understanding the semantics is key to avoiding architectural errors.

Namespace Resolution

Package import resolves names by adding the source namespace to the target namespace search path. It does not copy the class definitions. It keeps them in their original location.

Package merge, however, copies and integrates the content. The source package’s content effectively disappears into the target package after a successful merge. The original source package definition is often subsumed by the merged result.

Always check if you are trying to link or combine. If you link, import. If you combine, merge.

Dependency Tracking

In many modeling tools, package import is recorded as a dependency relationship. This allows you to generate reports on module coupling. It shows which parts of the system rely on others.

Package merge is usually not a dependency. It is a structural operation. Merging packages does not typically show up as a dependency in a coupling analysis because the packages are now one. They do not depend on each other; they are the same.

This distinction is vital for understanding your system’s complexity. Import adds to your coupling matrix. Merge reduces the number of packages you need to manage.

Impact on Code Generation

The choice between import and merge significantly impacts the generated code. Confusion here can lead to broken builds or duplicate classes.

Code Generation with Import

When using package import, the code generator creates a standard import or include statement. It maps the UML import to the language equivalent, such as import in Java or using in C#.

The generated code maintains the separation of files. The source file remains separate, and the target file references it. This preserves modularity and allows for independent compilation of the source module.

If you generate code from a merged model, you might get all the source code in a single file or a single package structure, depending on the generator’s settings.

Code Generation with Merge

Package merge often results in the generator treating the combined content as a single unit. This can lead to all classes being placed in the same namespace in the generated code.

This is useful when you want to generate a complete, monolithic library. However, it can also lead to namespace pollution if not managed carefully. Merging two packages with conflicting class names requires careful conflict resolution before code generation.

Always review the generated artifacts to ensure they match your architectural goals.

Comparison Summary

The following table summarizes the key differences to help you decide which operation to use.

Attribute	Package Import	Package Merge
Primary Goal	Reference / Usage	Unification / Consolidation
Namespace Change	Target sees source	Source becomes part of target
Dependency	Creates a dependency	Removes dependency (merges)
Structural Impact	None	Merges classifiers
Typical Use Case	Using a library	Integrating partial models

Best Practices for Modularization

To manage large UML models effectively, follow these best practices when deciding between import and merge.

• Use Import for Stability: Always use package import when you need to use an existing library or module. This preserves the integrity of the source module.
• Use Merge for Integration: Use package merge only when you are intentionally combining two partial models into a single, final design artifact.
• Avoid Circular Imports: Ensure that you do not create circular dependencies between imported packages. This leads to unresolved references in the model.
• Check for Naming Collisions: Before merging, ensure that no two classes have the same name unless they are intended to be merged. Name collisions cause errors.
• Document the Decision: Always document why you chose import vs merge in your architectural decisions. This helps future maintainers understand the structure.

Key Takeaways

• Package import creates a reference dependency without changing the source structure.
• Package merge combines two packages into a single unified structure.
• Import controls visibility; Merge controls structure and namespace.
• Use import for library usage and merge for model integration.
• Confusing these two concepts can lead to circular dependencies or duplicate classes.