/*
 * 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 <http://www.gnu.org/licenses/lgpl-2.1.html>.
 */
package org.hibernate.engine.jdbc.env.spi;

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

Helper for handling Identifier instances. 
Author:
Steve Ebersole/**
 * 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.
Params:
identifier – The identifier for which to normalize quoting.
Returns:
The quoting-normalized Identifier./**
	 * 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.
Params:
text – The text form of a name as obtained from mapping information.
Returns:
The identifier form of the name./**
	 * Generate an Identifier instance from its simple name as obtained from mapping
	 * information.
	 * <p/>
	 * 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.
Params:
text – The text form of a name as obtained from mapping information.
quoted – Is the identifier to be quoted explicitly.
Returns:
The identifier form of the name./**
	 * 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.
	 * <p/>
	 * 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 column-definition as defined by Column.columnDefinition(), 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 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. 
Params:
text – The text to be (possibly) quoted
See Also:
AvailableSettings.GLOBALLY_QUOTED_IDENTIFIERS_SKIP_COLUMN_DEFINITIONS
Returns:
The identifier form/**
	 * 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.
	 * <p/>
	 * 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.
Params:
word – The word to check
Returns:
true if the given word represents a reserved word; false otherwise./**
	 * 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 DatabaseMetaData calls. 
Params:
catalogIdentifier – The Identifier representation of a catalog name
Returns:
The String representation of the given catalog name/**
	 * 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 DatabaseMetaData calls. 
Params:
schemaIdentifier – The Identifier representation of a schema name
Returns:
The String representation of the given schema name/**
	 * 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 DatabaseMetaData calls. 
Params:
identifier – The Identifier representation of an object name
Returns:
The String representation of the given object name/**
	 * 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);
}