# Substituting Business Components

When customizing Business Components, you can use a Business Components for Java framework feature called substitution to build new applications. Substitution allows you to replace all occurrences and usages of the original component in the existing application with the customized component.

If you want one or more customized components to be completely substituted for existing components throughout your system, use the Substitution Panel in the Business Components Project wizard. You do not have to modify any of the delivered application's source code to accomplish this substitution. Instead, the wizard uses a factory-substitution design pattern to provide the Business Components for Java runtime system with a substitution table which maps the `OldName` of the existing component to the corresponding `NewName` which should replace it. Now, whenever the application tries to create a component of type `OldName`, it will create a component of type `NewName` instead. The wizard enters this information in your project's `.jpx` project definition file.

The Business Components for Java runtime does not typically read the project's .jpx file. To make the runtime read the .jpx file, you must add some additional information to the list of VM parameters and to the runtime classpath.

Note: | For the application model to remain valid, the custom component you are substituting must either directly or indirectly extend the original component.

The procedure for substituting Business Components is the same whether you are substituting Entity Objects, View Objects, Associations, View Links, or Application Modules. However, each component has its own substitution requirements and prerequisites. For more information about the requirements and prerequisites for substituting each component type, see these sections:

- Substituting Extended Entity Objects

- Substituting Extended View Objects

- Substituting Extended Associations

- Substituting Extended View Links

- Substituting Extended Application Modules

### To Substitute Business Components

1. Right-click the Project node and select Edit. The Business Components Project Wizard opens.

2. In the Substitutions panel, select the original component from the original package of components in the Available pane, and the new component from the package containing the extended components in the Substitutes pane, then click the Add button.

3. Click Finish to save the design time changes.

## Updating a Substitution Definition

After you have created an extended component and substituted it throughout your application, you might find that you want to test its behavior with a different extended component. In other words, you might want to replace one extended component with another. The Business Components for Java framework lets you substitute another extended component for the one you originally created.

The Update button on the Business Components Project wizard Substitution panel lets you replace one extended component with another extended component. For example, assume that you have used the Substitutions panel to substitute all instances of the `Emp` component with the `NewEmpEx` component. Assume also, that you have created a `TestEmp` component with different functionality than `NewEmpEx` and you want to test its performance in your application. To update the substitution from `NewEmpEx` to `TestEmp`, follow these steps:

1. Right-click the project's `.jpx` file and select Edit. The Business Components Project wizard opens.

2. In the Substitutions panel, select the substitution definition in the Substitutions list box that you want to update.

3. Select the original component `Emp` from the original package of components in the Available pane, then select the component with the new functionality that you want to test, `TestEmp` from the package containing the extended components in the Substitutes list box.

4. Click Update to replace the `NewEmpEx` substitution with `TestEmp`.

5. Click Finish to apply the Design Time changes.

## Removing a Substitution Definition

The Remove button on the Business Components Project wizard Substitution panel lets you discard the substitution of an extended component for an original component. Removing the substitution definition will cause the application to use the original component.

1. Right-click the project's `.jpx` file and select Edit. The Business Components Project wizard opens.

2. In the Substitutions panel, select the substitution definition in the Substitutions list box that you want to discard.

3. Click Remove to discard the substitution.

4. Click Finish to apply the Design Time changes.

## Applying the Substitutions at Runtime

After using the wizards to define the substitutions you want to make, the framework enters this information in the project's `.jpx` file. The Business Components for Java runtime does not typically read the project's `.jpx` file. To make the runtime read the `.jpx` file, you must add some additional information to the project properties::

- identify the name of the project file to the Java VM.

- add the project's directory path to the runtime classpath.

To add this information, follow these steps:

1. From the JDeveloper menu bar, select Project>Project Properties to open the Project Properties dialog.

2. Open the Run/Debug panel. In the Java VM Parameters field, enter:

> > `-Djbo.project=`name

> > where name represents the directory-qualified name of the project without the `.jpx` extension. For example:

> > `-Djbo.project=myProjects\ExtendProject`

3. Open the Paths panel and add the project's directory path to the Source root directories field.