Naming conventions

This section explains the naming conventions used when using remote databases with DirectQuery. When DirectQuery is used, the application will dynamically convert all Datastore Field and Store Names into a remote version. The remote version of the Datastore fields is what our remote database fields and tables should be named. If the Database and name mapper are out of sync, then the remote Tables/Fields may not be discoverable by the application. The interface INameMapper is used to convert Datastore field and store names into a format that works with remote databases.

Reference DirectQueryNameMapper

The reference DirectQueryNameMapper class is responsible for converting names from one format into another. It converts datastore fields or store names into a name that is more compatible with remote databases. Since some databases have strict naming conventions, the DirectQueryNameMapper is designed to handle most database naming conventions. The reference DirectQueryNameMapper works by taking a datastore name and converting it into one with the following logic:

Entire name is converted to uppercase
Spaces are replaced with underscores ’_’
CamelCase is split on the hump with underscores

The following conversions take place with the default DirectQueryNameMapper:

Input (local datastore) Name	Output (remote database) Name	Note
myvar	MYVAR	Set to uppercase
myVar	MY_VAR	CamelCase
MYVar	MYVAR	No change (because not camel case)
MYVAR	MYVAR	No change
MY_VAR	MY_VAR	No change
my var	MY_VAR	Space replaced with underscore

Custom naming conventions

To use custom naming conventions, create a custom implementation of the INameMapper interface and mark it as a spring component using the @Primary annotation so that this implementation takes precedence over the reference DirectQueryNameMapper. Then import the custom naming convention spring component into the ApplicationConfig (or into the FRTBConfig class).

Custom naming convention example

This example creates a custom naming convention that converts a given name into uppercase and replaces spaces with underscores ’_’. First, create a function that converts one way from the local name to the remote name:

	private String localToRemoteName(String localName){
		return localName
				.toUpperCase()
				.replace(' ', '_');
	}

However, converting remote names to local names is more difficult. To handle this, cache the names that have already been converted and perform the calculation when the CustomNameMapper is created. Use the IDatastoreSchemaDescription to help with the pre-caching.

@Component
public class CustomNameMapper implements INameMapper {

	private IDatastoreSchemaDescription datastoreSchemaDescription;

	private final Map<String, String> localToRemoteNames = new HashMap<>();
	private final Map<String, String> remoteToLocalNames = new HashMap<>();

	public CustomNameMapper(IDatastoreSchemaDescription datastoreSchemaDescription){
		this.datastoreSchemaDescription = datastoreSchemaDescription;
		init();
	}

	private void init(){
		for (var datastoreDescription : datastoreSchemaDescription.getStoreDescriptions()){

			// Convert Datastore Name:
			String datastoreName = datastoreDescription.getName();
			initCacheFor(datastoreName);

			// Convert Datastore Fields:
			for(String fieldName : datastoreDescription.getKeyFields()){
				initCacheFor(fieldName);
			}
		}
	}

	private void initCacheFor(String localName){
		String remoteName = localToRemoteName(localName);

		localToRemoteNames.put(localName, remoteName);
		remoteToLocalNames.put(remoteName, localName);
	}

	private String localToRemoteName(String localName){
		return localName
				.toUpperCase()
				.replace(' ', '_');
	}
}

Now complete the class by implementing the methods from the interface:

@Primary
@Component
public class CustomNameMapper implements INameMapper {

	private IDatastoreSchemaDescription datastoreSchemaDescription;

	private final Map<String, String> localToRemoteNames = new HashMap<>();
	private final Map<String, String> remoteToLocalNames = new HashMap<>();

	public CustomNameMapper(IDatastoreSchemaDescription datastoreSchemaDescription){
		this.datastoreSchemaDescription = datastoreSchemaDescription;
		init();
	}

	private void init(){
		for (var datastoreDescription : datastoreSchemaDescription.getStoreDescriptions()){

			// Convert Datastore Name:
			String datastoreName = datastoreDescription.getName();
			initCacheFor(datastoreName);

			// Convert Datastore Fields:
			for(String fieldName : datastoreDescription.getKeyFields()){
				initCacheFor(fieldName);
			}
		}
	}

	private void initCacheFor(String localName){
		String remoteName = localToRemoteName(localName);

		localToRemoteNames.put(localName, remoteName);
		remoteToLocalNames.put(remoteName, localName);
	}

	private String localToRemoteName(String localName){
		return localName
				.toUpperCase()
				.replace(' ', '_');
	}

	@Override public String convertToRemoteFieldName(String localStoreName, String localFieldName) {
		return localToRemoteNames.get(localFieldName);
	}

	@Override public String convertToLocalFieldName(String remoteTableName, String remoteFieldName) {
		return remoteToLocalNames.get(remoteFieldName);
	}

	@Override public String convertToRemoteFieldName(String localFieldName) {
		return localToRemoteNames.get(localFieldName);
	}

	@Override public String convertToLocalFieldName(String remoteFieldName) {
		return remoteToLocalNames.get(remoteFieldName);
	}

	@Override public String convertToRemoteTableName(String localStoreName) {
		return localToRemoteNames.get(localStoreName);
	}

	@Override public String convertToLocalStoreName(String remoteTableName) {
		return remoteToLocalNames.get(remoteTableName);
	}
}

Finally, add the custom name mapper to the ApplicationConfig (or into the FRTBConfig class):

@PropertySource(value = {
    ...
})
@Configuration
@Import(value = {
		...

		CustomNameMapper.class
})
public class FRTBConfig {

​Reference DirectQueryNameMapper

​Custom naming conventions

​Custom naming convention example

Reference DirectQueryNameMapper

Custom naming conventions

Custom naming convention example