org.hibernate.engine.jdbc.env.spi.IdentifierHelper Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of hibernate-core Show documentation
Hibernate's core ORM functionality
There is a newer version: 7.0.0.Alpha1
/*
 * Hibernate, Relational Persistence for Idiomatic Java
 *
 * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
 * See the lgpl.txt file in the root directory or .
 */
package org.hibernate.engine.jdbc.env.spi;

import org.hibernate.boot.model.naming.Identifier;
import org.hibernate.cfg.AvailableSettings;

/**
 * Helper for handling {@link Identifier} instances.
 *
 * @author Steve Ebersole
 */
public interface IdentifierHelper {
	/**
	 * Essentially quotes the identifier if it needs to be.  Useful to apply global quoting,
	 * as well as reserved word quoting after calls to naming strategies.
	 *
	 * @param identifier The identifier for which to normalize quoting.
	 *
	 * @return The quoting-normalized Identifier.
	 */
	Identifier normalizeQuoting(Identifier identifier);

	/**
	 * Generate an Identifier instance from its simple name as obtained from mapping
	 * information.
	 * 
	 * Note that Identifiers returned from here may be implicitly quoted based on
	 * 'globally quoted identifiers' or based on reserved words.
	 *
	 * @param text The text form of a name as obtained from mapping information.
	 *
	 * @return The identifier form of the name.
	 */
	Identifier toIdentifier(String text);

	/**
	 * Generate an Identifier instance from its simple name as obtained from mapping
	 * information.  Additionally, this form takes a boolean indicating whether to
	 * explicitly quote the Identifier.
	 * 

	 * Note that Identifiers returned from here may be implicitly quoted based on
	 * 'globally quoted identifiers' or based on reserved words.
	 *
	 * @param text The text form of a name as obtained from mapping information.
	 * @param quoted Is the identifier to be quoted explicitly.
	 *
	 * @return The identifier form of the name.
	 */
	Identifier toIdentifier(String text, boolean quoted);

	/**
	 * Intended only for use in handling quoting requirements for {@code column-definition}
	 * as defined by {@link javax.persistence.Column#columnDefinition()},
	 * {@link javax.persistence.JoinColumn#columnDefinition}, etc.  This method should not
	 * be called in any other scenario.
	 * 
	 * This method is needed to account for that fact that the JPA spec says that {@code column-definition}
	 * should be quoted of global-identifier-quoting is requested.  Again, this is needed for spec
	 * compliance.  TBH, I can not think of a argument why column-definitions should ever be *globally* quoted,
	 * but the spec is the spec.  In fact the default implementation allows applications to opt-out of
	 * global-identifier-quoting affecting column-definitions.
	 *
	 * @param text The text to be (possibly) quoted
	 *
	 * @return The identifier form
	 *
	 * @see AvailableSettings#GLOBALLY_QUOTED_IDENTIFIERS_SKIP_COLUMN_DEFINITIONS
	 */
	Identifier applyGlobalQuoting(String text);

	/**
	 * Check whether the given word represents a reserved word.
	 *
	 * @param word The word to check
	 *
	 * @return {@code true} if the given word represents a reserved word; {@code false} otherwise.
	 */
	boolean isReservedWord(String word);

	/**
	 * Render the Identifier representation of a catalog name into the String form needed
	 * in {@link java.sql.DatabaseMetaData} calls.
	 *
	 * @param catalogIdentifier The Identifier representation of a catalog name
	 *
	 * @return The String representation of the given catalog name
	 */
	String toMetaDataCatalogName(Identifier catalogIdentifier);

	/**
	 * Render the Identifier representation of a schema name into the String form needed
	 * in {@link java.sql.DatabaseMetaData} calls.
	 *
	 * @param schemaIdentifier The Identifier representation of a schema name
	 *
	 * @return The String representation of the given schema name
	 */
	String toMetaDataSchemaName(Identifier schemaIdentifier);

	/**
	 * Render the Identifier representation of an object name (table, sequence, etc) into the
	 * String form needed in {@link java.sql.DatabaseMetaData} calls.
	 *
	 * @param identifier The Identifier representation of an object name
	 *
	 * @return The String representation of the given object name
	 */
	String toMetaDataObjectName(Identifier identifier);
}