Java tutorial
/** * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information * regarding copyright ownership. The ASF licenses this file * to you under the Apache License, Version 2.0 (the * "License"); you may not use this file except in compliance * with the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS_METHOD IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.atlas.gremlin; import java.util.ArrayList; import java.util.Collections; import java.util.HashMap; import java.util.List; import java.util.Map; import org.apache.atlas.AtlasException; import org.apache.atlas.groovy.AbstractFunctionExpression; import org.apache.atlas.groovy.ArithmeticExpression; import org.apache.atlas.groovy.ArithmeticExpression.ArithmeticOperator; import org.apache.atlas.groovy.CastExpression; import org.apache.atlas.groovy.ClosureExpression; import org.apache.atlas.groovy.FieldExpression; import org.apache.atlas.groovy.FunctionCallExpression; import org.apache.atlas.groovy.GroovyExpression; import org.apache.atlas.groovy.IdentifierExpression; import org.apache.atlas.groovy.ListExpression; import org.apache.atlas.groovy.LiteralExpression; import org.apache.atlas.groovy.TraversalStepType; import org.apache.atlas.groovy.TypeCoersionExpression; import org.apache.atlas.groovy.VariableAssignmentExpression; import org.apache.atlas.query.GraphPersistenceStrategies; import org.apache.atlas.query.IntSequence; import org.apache.atlas.query.TypeUtils.FieldInfo; import org.apache.atlas.repository.graph.AtlasGraphProvider; import org.apache.atlas.repository.graphdb.AtlasEdgeDirection; import org.apache.atlas.repository.graphdb.GremlinVersion; import org.apache.atlas.typesystem.types.IDataType; import org.apache.atlas.typesystem.types.TypeSystem; import org.apache.atlas.typesystem.types.cache.TypeCache.TYPE_FILTER; import org.apache.atlas.util.AtlasRepositoryConfiguration; import com.google.common.collect.ImmutableList; /** * Factory to generate Groovy expressions representing Gremlin syntax that that * are independent of the specific version of Gremlin that is being used. * */ public abstract class GremlinExpressionFactory { private static final String G_VARIABLE = "g"; private static final String IT_VARIABLE = "it"; protected static final String SET_CLASS = "Set"; private static final String OBJECT_FIELD = "object"; protected static final String V_METHOD = "V"; protected static final String FILTER_METHOD = "filter"; private static final String PATH_METHOD = "path"; private static final String AS_METHOD = "as"; private static final String IN_OPERATOR = "in"; protected static final String HAS_METHOD = "has"; protected static final String TO_LOWER_CASE_METHOD = "toLowerCase"; protected static final String SELECT_METHOD = "select"; protected static final String ORDER_METHOD = "order"; protected static final String FILL_METHOD = "fill"; protected static final String MATCHES = "matches"; public static final GremlinExpressionFactory INSTANCE = AtlasGraphProvider.getGraphInstance() .getSupportedGremlinVersion() == GremlinVersion.THREE ? new Gremlin3ExpressionFactory() : new Gremlin2ExpressionFactory(); /** * Returns the unqualified name of the class used in this version of gremlin to * represent Gremlin queries as they are being generated. * @return */ public abstract String getTraversalExpressionClass(); /** * Gets the expression to use as the parent when translating the loop * expression in a loop * * @param inputQry * the * @return */ public abstract GroovyExpression getLoopExpressionParent(GroovyExpression inputQry); /** * Generates a loop expression. * * @param parent * the parent of the loop expression * @param emitExpr * Expression with the value that should be emitted by the loop * expression. * @param loopExpr * the query expression that is being executed repeatedly * executed in a loop * @param alias * The alias of the expression being looped over * @param times * the number of times to repeat, or null if a times condition * should not be used. * @return */ public abstract GroovyExpression generateLoopExpression(GroovyExpression parent, GraphPersistenceStrategies s, IDataType dataType, GroovyExpression loopExpr, String alias, Integer times); /** * Generates a logical (and/or) expression with the given operands. * @param parent * @param operator * @param operands * @return */ public abstract GroovyExpression generateLogicalExpression(GroovyExpression parent, String operator, List<GroovyExpression> operands); /** * Generates a back reference expression that refers to the given alias. * * @param parent * @param inSelect * @param alias * @return */ public abstract GroovyExpression generateBackReferenceExpression(GroovyExpression parent, boolean inSelect, String alias); /** * Generates a select expression * * @param parent * @param sourceNames * the names of the select fields * @param srcExprs * the corresponding values to return * @return */ public abstract GroovyExpression generateSelectExpression(GroovyExpression parent, List<LiteralExpression> sourceNames, List<GroovyExpression> srcExprs); /** * Generates a an expression that gets the value of the given property from the * vertex presented by the parent. * * @param parent * @param fInfo * @param propertyName * @param inSelect * @return */ public abstract GroovyExpression generateFieldExpression(GroovyExpression parent, FieldInfo fInfo, String propertyName, boolean inSelect); /** * Generates a has expression that checks whether the vertices match a specific condition * * @param s * @param parent the object that we should call apply the "has" condition to. * @param propertyName the name of the property whose value we are comparing * @param symbol comparsion operator symbol ('=','<', etc.) * @param requiredValue the value to compare against * @param fInfo info about the field whose value we are checking * @return * @throws AtlasException */ public abstract GroovyExpression generateHasExpression(GraphPersistenceStrategies s, GroovyExpression parent, String propertyName, String symbol, GroovyExpression requiredValue, FieldInfo fInfo) throws AtlasException; public abstract GroovyExpression generateLikeExpressionUsingFilter(GroovyExpression parent, String propertyName, GroovyExpression propertyValue) throws AtlasException; /** * Generates a range expression * * @param parent * @param startIndex * @param endIndex * @return */ public abstract GroovyExpression generateRangeExpression(GroovyExpression parent, int startIndex, int endIndex); /** * Determines if the specified expression is a range method call. * * @param expr * @return */ public abstract boolean isRangeExpression(GroovyExpression expr); /** * Set the start index and end index of a range expression * * @param expr * @param startIndex * @param endIndex */ public abstract void setRangeParameters(GroovyExpression expr, int startIndex, int endIndex); /** * If the specified function expression is a range expression, returns the start and end index parameters * otherwise returns null. * * @param expr * @return int array with two elements - element 0 is start index, element 1 is end index */ public abstract int[] getRangeParameters(AbstractFunctionExpression expr); /** * Generates an order by expression * * @param parent * @param translatedOrderBy * @param isAscending * @return */ public abstract GroovyExpression generateOrderByExpression(GroovyExpression parent, List<GroovyExpression> translatedOrderBy, boolean isAscending); /** * Determines if specified expression is an order method call * * @param expr * @return */ public boolean isOrderExpression(GroovyExpression expr) { if (expr instanceof FunctionCallExpression) { FunctionCallExpression functionCallExpression = (FunctionCallExpression) expr; if (functionCallExpression.getFunctionName().equals(ORDER_METHOD)) { return true; } } return false; } /** * Returns the Groovy expressions that should be used as the parents when * translating an order by expression. This is needed because Gremlin 2 and * 3 handle order by expressions very differently. * */ public abstract List<GroovyExpression> getOrderFieldParents(); /** * Returns the expression that represents an anonymous graph traversal. * * @return */ public abstract GroovyExpression getAnonymousTraversalExpression(); public boolean isLeafAnonymousTraversalExpression(GroovyExpression expr) { if (!(expr instanceof FunctionCallExpression)) { return false; } FunctionCallExpression functionCallExpr = (FunctionCallExpression) expr; if (functionCallExpr.getCaller() != null) { return false; } return functionCallExpr.getFunctionName().equals("_") & functionCallExpr.getArguments().size() == 0; } /** * Returns an expression representing * * @return */ public abstract GroovyExpression getFieldInSelect(); /** * Generates the expression the serves as the root of the Gremlin query. * @param varExpr variable containing the vertices to traverse * @return */ protected abstract GroovyExpression initialExpression(GroovyExpression varExpr, GraphPersistenceStrategies s); /** * Generates an expression that tests whether the vertex represented by the 'toTest' * expression represents an instance of the specified type, checking both the type * and super type names. * * @param s * @param typeName * @param itRef * @return */ protected abstract GroovyExpression typeTestExpression(GraphPersistenceStrategies s, String typeName, GroovyExpression vertexExpr); /** /** * Generates a sequence of groovy expressions that filter the vertices to only * those that match the specified type. If GraphPersistenceStrategies.collectTypeInstancesIntoVar() * is set and the gremlin optimizer is disabled, the vertices are put into a variable whose name is generated * from the specified IntSequence. The last item in the result will be a graph traversal restricted to only * the matching vertices. */ public List<GroovyExpression> generateTypeTestExpression(GraphPersistenceStrategies s, GroovyExpression parent, String typeName, IntSequence intSeq) throws AtlasException { if (AtlasRepositoryConfiguration.isGremlinOptimizerEnabled()) { GroovyExpression superTypeAttributeNameExpr = new LiteralExpression(s.superTypeAttributeName()); GroovyExpression typeNameExpr = new LiteralExpression(typeName); GroovyExpression superTypeMatchesExpr = new FunctionCallExpression(TraversalStepType.FILTER, HAS_METHOD, superTypeAttributeNameExpr, typeNameExpr); GroovyExpression typeAttributeNameExpr = new LiteralExpression(s.typeAttributeName()); GroovyExpression typeMatchesExpr = new FunctionCallExpression(TraversalStepType.FILTER, HAS_METHOD, typeAttributeNameExpr, typeNameExpr); GroovyExpression result = new FunctionCallExpression(TraversalStepType.FILTER, parent, "or", typeMatchesExpr, superTypeMatchesExpr); return Collections.singletonList(result); } else { if (s.filterBySubTypes()) { return typeTestExpressionUsingInFilter(s, parent, typeName); } else if (s.collectTypeInstancesIntoVar()) { return typeTestExpressionMultiStep(s, typeName, intSeq); } else { return typeTestExpressionUsingFilter(s, parent, typeName); } } } private List<GroovyExpression> typeTestExpressionUsingInFilter(GraphPersistenceStrategies s, GroovyExpression parent, final String typeName) throws AtlasException { List<GroovyExpression> typeNames = new ArrayList<>(); typeNames.add(new LiteralExpression(typeName)); Map<TYPE_FILTER, String> filters = new HashMap<TYPE_FILTER, String>() { { put(TYPE_FILTER.SUPERTYPE, typeName); } }; ImmutableList<String> subTypes = TypeSystem.getInstance().getTypeNames(filters); if (!subTypes.isEmpty()) { for (String subType : subTypes) { typeNames.add(new LiteralExpression(subType)); } } GroovyExpression inFilterExpr = generateHasExpression(s, parent, s.typeAttributeName(), IN_OPERATOR, new ListExpression(typeNames), null); return Collections.singletonList(inFilterExpr); } private List<GroovyExpression> typeTestExpressionMultiStep(GraphPersistenceStrategies s, String typeName, IntSequence intSeq) { String varName = "_var_" + intSeq.next(); GroovyExpression varExpr = new IdentifierExpression(varName); List<GroovyExpression> result = new ArrayList<>(); result.add(newSetVar(varName)); result.add(fillVarWithTypeInstances(s, typeName, varName)); result.add(fillVarWithSubTypeInstances(s, typeName, varName)); result.add(initialExpression(varExpr, s)); return result; } private GroovyExpression newSetVar(String varName) { GroovyExpression castExpr = new TypeCoersionExpression(new ListExpression(), SET_CLASS); return new VariableAssignmentExpression(varName, castExpr); } private GroovyExpression fillVarWithTypeInstances(GraphPersistenceStrategies s, String typeName, String fillVar) { GroovyExpression graphExpr = getAllVerticesExpr(); GroovyExpression typeAttributeNameExpr = new LiteralExpression(s.typeAttributeName()); GroovyExpression typeNameExpr = new LiteralExpression(typeName); GroovyExpression hasExpr = new FunctionCallExpression(graphExpr, HAS_METHOD, typeAttributeNameExpr, typeNameExpr); GroovyExpression fillExpr = new FunctionCallExpression(hasExpr, FILL_METHOD, new IdentifierExpression(fillVar)); return fillExpr; } private GroovyExpression fillVarWithSubTypeInstances(GraphPersistenceStrategies s, String typeName, String fillVar) { GroovyExpression graphExpr = getAllVerticesExpr(); GroovyExpression superTypeAttributeNameExpr = new LiteralExpression(s.superTypeAttributeName()); GroovyExpression typeNameExpr = new LiteralExpression(typeName); GroovyExpression hasExpr = new FunctionCallExpression(graphExpr, HAS_METHOD, superTypeAttributeNameExpr, typeNameExpr); GroovyExpression fillExpr = new FunctionCallExpression(hasExpr, FILL_METHOD, new IdentifierExpression(fillVar)); return fillExpr; } private List<GroovyExpression> typeTestExpressionUsingFilter(GraphPersistenceStrategies s, GroovyExpression parent, String typeName) { GroovyExpression itExpr = getItVariable(); GroovyExpression typeTestExpr = typeTestExpression(s, typeName, itExpr); GroovyExpression closureExpr = new ClosureExpression(typeTestExpr); GroovyExpression filterExpr = new FunctionCallExpression(parent, FILTER_METHOD, closureExpr); return Collections.singletonList(filterExpr); } /** * Generates an expression which checks whether the vertices in the query have * a field with the given name. * * @param parent * @param fieldName * @return */ public GroovyExpression generateUnaryHasExpression(GroovyExpression parent, String fieldName) { return new FunctionCallExpression(TraversalStepType.FILTER, parent, HAS_METHOD, new LiteralExpression(fieldName)); } /** * Generates a path expression * * @param parent * @return */ public GroovyExpression generatePathExpression(GroovyExpression parent) { return new FunctionCallExpression(TraversalStepType.MAP_TO_VALUE, parent, PATH_METHOD); } /** * Generates the emit expression used in loop expressions. * @param s * @param dataType * @return */ protected GroovyExpression generateLoopEmitExpression(GraphPersistenceStrategies s, IDataType dataType) { return typeTestExpression(s, dataType.getName(), getCurrentObjectExpression()); } /** * Generates an alias expression * * @param parent * @param alias * @return */ public GroovyExpression generateAliasExpression(GroovyExpression parent, String alias) { return new FunctionCallExpression(TraversalStepType.SIDE_EFFECT, parent, AS_METHOD, new LiteralExpression(alias)); } /** * Generates an expression that gets the vertices adjacent to the vertex in 'parent' * in the specified direction. * * @param parent * @param dir * @return */ public GroovyExpression generateAdjacentVerticesExpression(GroovyExpression parent, AtlasEdgeDirection dir) { return new FunctionCallExpression(TraversalStepType.FLAT_MAP_TO_ELEMENTS, parent, getGremlinFunctionName(dir)); } private String getGremlinFunctionName(AtlasEdgeDirection dir) { switch (dir) { case IN: return "in"; case OUT: return "out"; case BOTH: return "both"; default: throw new RuntimeException("Unknown Atlas Edge Direction: " + dir); } } /** * Generates an expression that gets the vertices adjacent to the vertex in 'parent' * in the specified direction, following only edges with the given label. * * @param parent * @param dir * @return */ public GroovyExpression generateAdjacentVerticesExpression(GroovyExpression parent, AtlasEdgeDirection dir, String label) { return new FunctionCallExpression(TraversalStepType.FLAT_MAP_TO_ELEMENTS, parent, getGremlinFunctionName(dir), new LiteralExpression(label)); } /** * Generates an arithmetic expression, e.g. a + b * */ public GroovyExpression generateArithmeticExpression(GroovyExpression left, String operator, GroovyExpression right) throws AtlasException { ArithmeticOperator op = ArithmeticOperator.lookup(operator); return new ArithmeticExpression(left, op, right); } public abstract GroovyExpression generateGroupByExpression(GroovyExpression parent, GroovyExpression groupByExpression, GroovyExpression aggregationFunction); protected GroovyExpression getItVariable() { return new IdentifierExpression(IT_VARIABLE); } protected GroovyExpression getAllVerticesExpr() { GroovyExpression gExpr = getGraphExpression(); return new FunctionCallExpression(TraversalStepType.START, gExpr, V_METHOD); } protected IdentifierExpression getGraphExpression() { return new IdentifierExpression(TraversalStepType.SOURCE, G_VARIABLE); } protected GroovyExpression getCurrentObjectExpression() { return new FieldExpression(getItVariable(), OBJECT_FIELD); } //assumes cast already performed public GroovyExpression generateCountExpression(GroovyExpression itExpr) { GroovyExpression collectionExpr = new CastExpression(itExpr, "Collection"); return new FunctionCallExpression(collectionExpr, "size"); } public GroovyExpression generateMinExpression(GroovyExpression itExpr, GroovyExpression mapFunction) { return getAggregrationExpression(itExpr, mapFunction, "min"); } public GroovyExpression generateMaxExpression(GroovyExpression itExpr, GroovyExpression mapFunction) { return getAggregrationExpression(itExpr, mapFunction, "max"); } public GroovyExpression generateSumExpression(GroovyExpression itExpr, GroovyExpression mapFunction) { return getAggregrationExpression(itExpr, mapFunction, "sum"); } private GroovyExpression getAggregrationExpression(GroovyExpression itExpr, GroovyExpression mapFunction, String functionName) { GroovyExpression collectionExpr = new CastExpression(itExpr, "Collection"); ClosureExpression collectFunction = new ClosureExpression(mapFunction); GroovyExpression transformedList = new FunctionCallExpression(collectionExpr, "collect", collectFunction); return new FunctionCallExpression(transformedList, functionName); } public GroovyExpression getClosureArgumentValue() { return getItVariable(); } /** * Specifies the parent to use when translating the select list in * a group by statement. * * @return */ public abstract GroovyExpression getGroupBySelectFieldParent(); public GroovyExpression generateFillExpression(GroovyExpression parent, GroovyExpression variable) { return new FunctionCallExpression(TraversalStepType.END, parent, "fill", variable); } /** * Generates an anonymous graph traversal initialized with the specified value. In Gremlin 3, we need * to use a different syntax for this when the object is a map, so that information needs to be provided * to this method so that the correct syntax is used. * * @param isMap true if the value contains Map instances, false if it contains Vertex instances * @param valueCollection the source objects to start the traversal from. */ public abstract GroovyExpression generateSeededTraversalExpresssion(boolean isMap, GroovyExpression valueCollection); /** * Returns the current value of the traverser. This is used when generating closure expressions that * need to operate on the current value in the graph graversal. * * @param traverser * @return */ public abstract GroovyExpression getCurrentTraverserObject(GroovyExpression traverser); /** * Generates an expression that transforms the current value of the traverser by * applying the function specified * * @param parent * @param closureExpression * @return */ public abstract GroovyExpression generateMapExpression(GroovyExpression parent, ClosureExpression closureExpression); /** * Returns whether a select statement generates a map (or Gremlin 2 "Row") when it contains the specified * number of aliases. * */ public abstract boolean isSelectGeneratesMap(int aliasCount); /** * Generates an expression to get the value of the value from the row map * generated by select() with the specified key. * */ public abstract GroovyExpression generateGetSelectedValueExpression(LiteralExpression key, GroovyExpression rowMapExpr); public GroovyExpression removeExtraMapFromPathInResult(GroovyExpression parent) { GroovyExpression listItem = getItVariable(); GroovyExpression tailExpr = new FunctionCallExpression(listItem, "tail"); return new FunctionCallExpression(parent, "collect", new ClosureExpression(tailExpr)); } /** * Generates a toList expression to execute the gremlin query and * store the result in a new list. * * @param expr * @return */ public GroovyExpression generateToListExpression(GroovyExpression expr) { return new FunctionCallExpression(TraversalStepType.END, expr, "toList"); } /** * Finds aliases that absolutely must be brought along with this expression into * the output expression and cannot just be recreated there. For example, in the * Gremlin 2 loop expression, the loop semantics break of the alias is simply recreated * in the output expression. * @param expr * @return */ public abstract List<String> getAliasesRequiredByExpression(GroovyExpression expr); /** * Checks if the given expression is an alias expression, and if so * returns the alias from the expression. Otherwise, null is * returned. */ public String getAliasNameIfRelevant(GroovyExpression expr) { if (!(expr instanceof FunctionCallExpression)) { return null; } FunctionCallExpression fc = (FunctionCallExpression) expr; if (!fc.getFunctionName().equals(AS_METHOD)) { return null; } LiteralExpression aliasName = (LiteralExpression) fc.getArguments().get(0); return aliasName.getValue().toString(); } public abstract boolean isRepeatExpression(GroovyExpression expr); }