| /* |
| * Copyright (c) 2006, 2021 Oracle and/or its affiliates. All rights reserved. |
| * |
| * This program and the accompanying materials are made available under the |
| * terms of the Eclipse Public License v. 2.0 which is available at |
| * http://www.eclipse.org/legal/epl-2.0, |
| * or the Eclipse Distribution License v. 1.0 which is available at |
| * http://www.eclipse.org/org/documents/edl-v10.php. |
| * |
| * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause |
| */ |
| |
| // Contributors: |
| // Oracle - initial API and implementation |
| // |
| package org.eclipse.persistence.jpa.jpql.tools; |
| |
| import org.eclipse.persistence.jpa.jpql.parser.IdentifierRole; |
| import org.eclipse.persistence.jpa.jpql.tools.spi.IEntity; |
| import org.eclipse.persistence.jpa.jpql.tools.spi.IMapping; |
| import org.eclipse.persistence.jpa.jpql.tools.spi.IType; |
| |
| /** |
| * This object stores the various proposals available for content assist for a certain position |
| * within a JPQL query. The proposals are stored in categories (abstract schema types, identifiers, |
| * identification variables and mappings). |
| * <p> |
| * Provisional API: This interface is part of an interim API that is still under development and |
| * expected to change significantly before reaching stability. It is available at this early stage |
| * to solicit feedback from pioneering adopters on the understanding that any code that uses this |
| * API will almost certainly be broken (repeatedly) as the API evolves. |
| * |
| * @version 2.5 |
| * @since 2.3 |
| * @author Pascal Filion |
| */ |
| public interface ContentAssistProposals { |
| |
| /** |
| * Returns the collection of possible abstract schema types. |
| * |
| * @return The {@link IEntity entities} defined in the persistence context |
| */ |
| Iterable<IEntity> abstractSchemaTypes(); |
| |
| /** |
| * Creates a new JPQL query by inserting the given proposal at the given position. The updated |
| * JPQL query and position will be adjusted by converting some characters into their corresponding |
| * escaped characters, for instance '\r' will be converted to '\\r. |
| * <p> |
| * The replacement will also handle compound JPQL identifiers when updating the JPQL query. |
| * <p> |
| * Example: If the cursor is within "IS NOT N|" and the proposal is "IS NOT NULL", then "IS NOT" |
| * will not be added twice. If the word to replace is "IS NULL" and the proposal is "IS NOT NULL", |
| * then "NOT" will be inserted between "IS" and "NULL". |
| * |
| * @param jpqlQuery The JPQL query to modify with the given proposal |
| * @param proposal The proposal to insert into the query |
| * @param position The position of insertion |
| * @param insert Flag that determines if the partial word following the cursor should be left |
| * intact or should be replaced by the proposal |
| * @return The result of inserting the proposal into the query, including the adjust position, if |
| * it was required |
| */ |
| ResultQuery buildEscapedQuery(String jpqlQuery, String proposal, int position, boolean insert); |
| |
| /** |
| * Creates a new JPQL query by inserting the given proposal at the given position. |
| * <p> |
| * The replacement will also handle compound JPQL identifiers when updating the JPQL query. |
| * <p> |
| * Example: If the cursor is within "IS NOT N|" and the proposal is "IS NOT NULL", then "IS NOT" |
| * will not be added twice. If the word to replace is "IS NULL" and the proposal is "IS NOT NULL", |
| * then "NOT" will be inserted between "IS" and "NULL". |
| * |
| * @param jpqlQuery The JPQL query to modify with the given proposal |
| * @param proposal The proposal to insert into the query |
| * @param position The position of insertion |
| * @param insert Flag that determines if the partial word following the cursor should be left |
| * intact or should be replaced by the proposal |
| * @return The result of inserting the proposal into the query, including the adjust position, if |
| * it was required |
| */ |
| ResultQuery buildQuery(String jpqlQuery, String proposal, int position, boolean insert); |
| |
| /** |
| * Creates a new JPQL query by inserting the given proposal at the given position. The updated |
| * JPQL query and position will be adjusted by converting some characters into their corresponding |
| * escaped characters, for instance '>' will be converted to '&gt;'. |
| * <p> |
| * The replacement will also handle compound JPQL identifiers when updating the JPQL query. |
| * <p> |
| * Example: If the cursor is within "IS NOT N|" and the proposal is "IS NOT NULL", then "IS NOT" |
| * will not be added twice. If the word to replace is "IS NULL" and the proposal is "IS NOT NULL", |
| * then "NOT" will be inserted between "IS" and "NULL". |
| * |
| * @param jpqlQuery The JPQL query to modify with the given proposal, which should be the non- |
| * converted string, i.e. any escaped characters should not be converted |
| * @param proposal The proposal to insert into the query |
| * @param position The position of insertion, which was derived from the parsed tree representation |
| * of the JPQL query |
| * @param insert Flag that determines if the partial word following the cursor should be left |
| * intact or should be replaced by the proposal |
| * @return The result of inserting the proposal into the query, including the adjust position, if |
| * it was required |
| * @since 2.5 |
| */ |
| ResultQuery buildXmlQuery(String jpqlQuery, String proposal, int position, boolean insert); |
| |
| /** |
| * Returns the filtered list of possible class names. This is usually available when the cursor |
| * is within the constructor name of the constructor expression. |
| * |
| * @return The filtered list of possible class names |
| * @see org.eclipse.persistence.jpa.jpql.parser.ConstructorExpression |
| * @since 2.5 |
| */ |
| Iterable<String> classNames(); |
| |
| /** |
| * Returns the filtered list of possible column names. |
| * |
| * @return The filtered list of possible column names |
| * @since 2.5 |
| */ |
| Iterable<String> columnNames(); |
| |
| /** |
| * Returns the filtered list of possible enum constant names. This is usually available when the |
| * cursor is after the dot separating a fully qualified enum type and the enum constant. |
| * |
| * @return The filtered list of possible enum constant names associated with its enum type |
| * @since 2.5 |
| */ |
| Iterable<EnumProposals> enumConstant(); |
| |
| /** |
| * Retrieves the abstract schema type that is mapped with the given identification variable. |
| * |
| * @param identificationVariable The identification variable that, if defined as a range variable, |
| * will be mapped to a managed type |
| * @return The abstract schema type mapped with the given identification variable or |
| * <code>null</code> if the given variable is mapped to something else or not mapped to anything |
| */ |
| IEntity getAbstractSchemaType(String identificationVariable); |
| |
| /** |
| * @since 2.5 |
| */ |
| ClassType getClassType(); |
| |
| /** |
| * Returns the role of the given JPQL identifier. |
| * |
| * @param identifier The JPQL identifier to retrieve its role |
| * @return The {@link IdentifierRole} for the given JPQL identifier or <code>null</code> if no |
| * role was defined or if the given string is not a valid JPQL identifier |
| * @since 2.4 |
| */ |
| IdentifierRole getIdentifierRole(String identifier); |
| |
| /** |
| * Determines whether there is at least one proposals. |
| * |
| * @return <code>true</code> if there is at least one proposal; otherwise <code>false</code> |
| */ |
| boolean hasProposals(); |
| |
| /** |
| * Returns the collection of possible identification variables. |
| * |
| * @return The list of possible identification variables |
| */ |
| Iterable<String> identificationVariables(); |
| |
| /** |
| * Returns the collection of possible JPQL identifiers. |
| * |
| * @return The list of possible JPQL identifiers |
| */ |
| Iterable<String> identifiers(); |
| |
| /** |
| * Returns the collection of possible {@link IMapping mappings}, which can be state fields, |
| * association fields and/or collection fields depending on the location used to retrieve the |
| * possible proposals. |
| * |
| * @return The list of possible proposals {@link IMapping mappings} |
| */ |
| Iterable<IMapping> mappings(); |
| |
| /** |
| * Returns the filtered list of possible table names. |
| * |
| * @return The filtered list of possible table names |
| * @since 2.5 |
| */ |
| Iterable<String> tableNames(); |
| |
| /** |
| * This enumeration determines the type of classes returned by {@link ContentAssistProposals#classNames()}. |
| */ |
| enum ClassType { |
| |
| /** |
| * Indicates the only class type allowed is an enum type. |
| */ |
| ENUM, |
| |
| /** |
| * Indicates the class has to be instantiable, i.e. anonymous, interfaces, enums, annotations |
| * are not allowed. |
| */ |
| INSTANTIABLE |
| } |
| |
| /** |
| * Holds onto the {@link IType} of the enum type and the list of possible enum constants. |
| * |
| * @version 2.5 |
| */ |
| interface EnumProposals { |
| |
| /** |
| * Returns the list of enum constants that have been filtered. |
| */ |
| Iterable<String> enumConstants(); |
| |
| /** |
| * The {@link IType} representing the enum type. |
| * |
| * @return The {@link IType} representing the enum type |
| */ |
| IType enumType(); |
| } |
| } |