Navigation :

Naming Conventions

This section explains the naming conventions used when using remote databases with DirectQuery.

When DirectQuery is used, the application dynamically converts 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 Fields 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. We use this to convert Datastore Fields or Store names into a name that is more compatible with remote databases. Since some databases have strict naming conventions, we have designed our DirectQueryNameMapper 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 upper case.
Spaces are replaced with underscores ‘_’.
Camel case is split on the hump with underscores.

So we can expect the following conversions to take place with the default DirectQueryNameMapper:

Input (local datastore) Name	Output (remote database) Name	Note
myvar	MYVAR	Set to uppercase
myVar	MY_VAR	camel case
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.
Mark it as a Spring component using the @Primary annotation, so that your implementation takes precedence over the reference DirectQueryNameMapper.
Import your custom naming convention Spring component into your main application configuration file, or into the MRDirectQueryConfig class.

Custom Naming Convention Example

Here we create a custom naming convention that converts a given name into uppercase and replaces spaces with underscores ‘_’.

First, we create a function that will convert one way from the local name to the remote name:

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

However, we will have difficulties when converting remote names to local names. To handle this, we can cache the names that we have already converted and perform the calculation when our CustomNameMapper is created.

We will use the IDatastoreSchemaDescription to help us with our 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 we can complete our 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, we add our custom name mapper to our application configuration file, or into the MRDirectQueryConfig class:

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

		CustomNameMapper.class
})
public class MRDirectQueryConfig {