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 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.tinkerpop.gremlin.server.op; import io.netty.channel.ChannelHandlerContext; import org.apache.commons.lang.time.StopWatch; import org.apache.tinkerpop.gremlin.driver.MessageSerializer; import org.apache.tinkerpop.gremlin.driver.Tokens; import org.apache.tinkerpop.gremlin.driver.message.RequestMessage; import org.apache.tinkerpop.gremlin.driver.message.ResponseMessage; import org.apache.tinkerpop.gremlin.driver.message.ResponseStatusCode; import org.apache.tinkerpop.gremlin.driver.ser.MessageTextSerializer; import org.apache.tinkerpop.gremlin.server.Context; import org.apache.tinkerpop.gremlin.server.GraphManager; import org.apache.tinkerpop.gremlin.server.OpProcessor; import org.apache.tinkerpop.gremlin.server.Settings; import org.apache.tinkerpop.gremlin.server.handler.Frame; import org.apache.tinkerpop.gremlin.server.handler.StateKey; import org.apache.tinkerpop.gremlin.server.util.ExceptionHelper; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import java.util.ArrayList; import java.util.Collections; import java.util.HashSet; import java.util.Iterator; import java.util.List; import java.util.Map; import java.util.concurrent.TimeUnit; import java.util.concurrent.TimeoutException; /** * A base {@link OpProcessor} implementation that processes an {@code Iterator} of results in a generalized way while * ensuring that graph transactions are properly managed. * * @author Stephen Mallette (http://stephen.genoprime.com) */ public abstract class AbstractOpProcessor implements OpProcessor { private static final Logger logger = LoggerFactory.getLogger(AbstractEvalOpProcessor.class); /** * When set to {@code true}, transactions are always managed otherwise they can be overridden by the request. */ protected final boolean manageTransactions; protected AbstractOpProcessor(final boolean manageTransactions) { this.manageTransactions = manageTransactions; } /** * Provides a generic way of iterating a result set back to the client. Implementers should respect the * {@link Settings#serializedResponseTimeout} configuration and break the serialization process if * it begins to take too long to do so, throwing a {@link java.util.concurrent.TimeoutException} in such * cases. * * @param context The Gremlin Server {@link Context} object containing settings, request message, etc. * @param itty The result to iterator * @throws TimeoutException if the time taken to serialize the entire result set exceeds the allowable time. */ protected void handleIterator(final Context context, final Iterator itty) throws TimeoutException, InterruptedException { final ChannelHandlerContext ctx = context.getChannelHandlerContext(); final RequestMessage msg = context.getRequestMessage(); final Settings settings = context.getSettings(); final MessageSerializer serializer = ctx.channel().attr(StateKey.SERIALIZER).get(); final boolean useBinary = ctx.channel().attr(StateKey.USE_BINARY).get(); boolean warnOnce = false; // sessionless requests are always transaction managed, but in-session requests are configurable. final boolean managedTransactionsForRequest = manageTransactions ? true : (Boolean) msg.getArgs().getOrDefault(Tokens.ARGS_MANAGE_TRANSACTION, false); // we have an empty iterator - happens on stuff like: g.V().iterate() if (!itty.hasNext()) { // as there is nothing left to iterate if we are transaction managed then we should execute a // commit here before we send back a NO_CONTENT which implies success if (managedTransactionsForRequest) attemptCommit(msg, context.getGraphManager(), settings.strictTransactionManagement); ctx.writeAndFlush(ResponseMessage.build(msg).code(ResponseStatusCode.NO_CONTENT).create()); return; } // timer for the total serialization time final StopWatch stopWatch = new StopWatch(); stopWatch.start(); // the batch size can be overridden by the request final int resultIterationBatchSize = (Integer) msg.optionalArgs(Tokens.ARGS_BATCH_SIZE) .orElse(settings.resultIterationBatchSize); List<Object> aggregate = new ArrayList<>(resultIterationBatchSize); // use an external control to manage the loop as opposed to just checking hasNext() in the while. this // prevent situations where auto transactions create a new transaction after calls to commit() withing // the loop on calls to hasNext(). boolean hasMore = itty.hasNext(); while (hasMore) { if (Thread.interrupted()) throw new InterruptedException(); // check if an implementation needs to force flush the aggregated results before the iteration batch // size is reached. final boolean forceFlush = isForceFlushed(ctx, msg, itty); // have to check the aggregate size because it is possible that the channel is not writeable (below) // so iterating next() if the message is not written and flushed would bump the aggregate size beyond // the expected resultIterationBatchSize. Total serialization time for the response remains in // effect so if the client is "slow" it may simply timeout. // // there is a need to check hasNext() on the iterator because if the channel is not writeable the // previous pass through the while loop will have next()'d the iterator and if it is "done" then a // NoSuchElementException will raise its head. also need a check to ensure that this iteration doesn't // require a forced flush which can be forced by sub-classes. // // this could be placed inside the isWriteable() portion of the if-then below but it seems better to // allow iteration to continue into a batch if that is possible rather than just doing nothing at all // while waiting for the client to catch up if (aggregate.size() < resultIterationBatchSize && itty.hasNext() && !forceFlush) aggregate.add(itty.next()); // send back a page of results if batch size is met or if it's the end of the results being iterated. // also check writeability of the channel to prevent OOME for slow clients. if (ctx.channel().isWritable()) { if (forceFlush || aggregate.size() == resultIterationBatchSize || !itty.hasNext()) { final ResponseStatusCode code = itty.hasNext() ? ResponseStatusCode.PARTIAL_CONTENT : ResponseStatusCode.SUCCESS; // serialize here because in sessionless requests the serialization must occur in the same // thread as the eval. as eval occurs in the GremlinExecutor there's no way to get back to the // thread that processed the eval of the script so, we have to push serialization down into that Frame frame = null; try { frame = makeFrame(ctx, msg, serializer, useBinary, aggregate, code, generateMetaData(ctx, msg, code, itty)); } catch (Exception ex) { // a frame may use a Bytebuf which is a countable release - if it does not get written // downstream it needs to be released here if (frame != null) frame.tryRelease(); // exception is handled in makeFrame() - serialization error gets written back to driver // at that point if (managedTransactionsForRequest) attemptRollback(msg, context.getGraphManager(), settings.strictTransactionManagement); break; } // track whether there is anything left in the iterator because it needs to be accessed after // the transaction could be closed - in that case a call to hasNext() could open a new transaction // unintentionally final boolean moreInIterator = itty.hasNext(); try { // only need to reset the aggregation list if there's more stuff to write if (moreInIterator) aggregate = new ArrayList<>(resultIterationBatchSize); else { // iteration and serialization are both complete which means this finished successfully. note that // errors internal to script eval or timeout will rollback given GremlinServer's global configurations. // local errors will get rolledback below because the exceptions aren't thrown in those cases to be // caught by the GremlinExecutor for global rollback logic. this only needs to be committed if // there are no more items to iterate and serialization is complete if (managedTransactionsForRequest) attemptCommit(msg, context.getGraphManager(), settings.strictTransactionManagement); // exit the result iteration loop as there are no more results left. using this external control // because of the above commit. some graphs may open a new transaction on the call to // hasNext() hasMore = false; } } catch (Exception ex) { // a frame may use a Bytebuf which is a countable release - if it does not get written // downstream it needs to be released here if (frame != null) frame.tryRelease(); throw ex; } if (!moreInIterator) iterateComplete(ctx, msg, itty); // the flush is called after the commit has potentially occurred. in this way, if a commit was // required then it will be 100% complete before the client receives it. the "frame" at this point // should have completely detached objects from the transaction (i.e. serialization has occurred) // so a new one should not be opened on the flush down the netty pipeline ctx.writeAndFlush(frame); } } else { // don't keep triggering this warning over and over again for the same request if (!warnOnce) { logger.warn( "Pausing response writing as writeBufferHighWaterMark exceeded on {} - writing will continue once client has caught up", msg); warnOnce = true; } // since the client is lagging we can hold here for a period of time for the client to catch up. // this isn't blocking the IO thread - just a worker. TimeUnit.MILLISECONDS.sleep(10); } stopWatch.split(); if (settings.serializedResponseTimeout > 0 && stopWatch.getSplitTime() > settings.serializedResponseTimeout) { final String timeoutMsg = String.format( "Serialization of the entire response exceeded the 'serializeResponseTimeout' setting %s", warnOnce ? "[Gremlin Server paused writes to client as messages were not being consumed quickly enough]" : ""); throw new TimeoutException(timeoutMsg.trim()); } stopWatch.unsplit(); } stopWatch.stop(); } /** * Called when iteration within {@link #handleIterator(Context, Iterator)} is on its final pass and the final * frame is about to be sent back to the client. This method only gets called on successful iteration of the * entire result. */ protected void iterateComplete(final ChannelHandlerContext ctx, final RequestMessage msg, final Iterator itty) { // do nothing by default } /** * Determines if a {@link Frame} should be force flushed outside of the {@code resultIterationBatchSize} and the * termination of the iterator. By default this method return {@code false}. * * @param itty a reference to the current {@link Iterator} of results - it is not meant to be forwarded in * this method */ protected boolean isForceFlushed(final ChannelHandlerContext ctx, final RequestMessage msg, final Iterator itty) { return false; } /** * Generates meta-data to put on a {@link ResponseMessage}. * * @param itty a reference to the current {@link Iterator} of results - it is not meant to be forwarded in * this method */ protected Map<String, Object> generateMetaData(final ChannelHandlerContext ctx, final RequestMessage msg, final ResponseStatusCode code, final Iterator itty) { return Collections.emptyMap(); } /** * @deprecated As of release 3.2.2, replaced by {@link #makeFrame(ChannelHandlerContext, RequestMessage, MessageSerializer, boolean, List, ResponseStatusCode, Map)}. */ protected static Frame makeFrame(final ChannelHandlerContext ctx, final RequestMessage msg, final MessageSerializer serializer, final boolean useBinary, final List<Object> aggregate, final ResponseStatusCode code) throws Exception { return makeFrame(ctx, msg, serializer, useBinary, aggregate, code, Collections.emptyMap()); } protected static Frame makeFrame(final ChannelHandlerContext ctx, final RequestMessage msg, final MessageSerializer serializer, final boolean useBinary, final List<Object> aggregate, final ResponseStatusCode code, final Map<String, Object> responseMetaData) throws Exception { try { if (useBinary) { return new Frame(serializer.serializeResponseAsBinary(ResponseMessage.build(msg).code(code) .responseMetaData(responseMetaData).result(aggregate).create(), ctx.alloc())); } else { // the expectation is that the GremlinTextRequestDecoder will have placed a MessageTextSerializer // instance on the channel. final MessageTextSerializer textSerializer = (MessageTextSerializer) serializer; return new Frame(textSerializer.serializeResponseAsString(ResponseMessage.build(msg).code(code) .responseMetaData(responseMetaData).result(aggregate).create())); } } catch (Exception ex) { logger.warn("The result [{}] in the request {} could not be serialized and returned.", aggregate, msg.getRequestId(), ex); final String errorMessage = String.format("Error during serialization: %s", ExceptionHelper.getMessageFromExceptionOrCause(ex)); final ResponseMessage error = ResponseMessage.build(msg.getRequestId()).statusMessage(errorMessage) .statusAttributeException(ex).code(ResponseStatusCode.SERVER_ERROR_SERIALIZATION).create(); ctx.writeAndFlush(error); throw ex; } } protected static void attemptCommit(final RequestMessage msg, final GraphManager graphManager, final boolean strict) { if (strict) { // validations should have already been performed in StandardOpProcessor, but a failure in bindings maker // at the time of the eval might raise through here at which point the validation didn't yet happen. better // to just check again final boolean hasRebindings = msg.getArgs().containsKey(Tokens.ARGS_REBINDINGS); final String rebindingOrAliasParameter = hasRebindings ? Tokens.ARGS_REBINDINGS : Tokens.ARGS_ALIASES; if (msg.getArgs().containsKey(rebindingOrAliasParameter)) { final Map<String, String> aliases = (Map<String, String>) msg.getArgs() .get(rebindingOrAliasParameter); graphManager.commit(new HashSet<>(aliases.values())); } else { graphManager.commitAll(); } } else { graphManager.commitAll(); } } protected static void attemptRollback(final RequestMessage msg, final GraphManager graphManager, final boolean strict) { if (strict) { // validations should have already been performed in StandardOpProcessor, but a failure in bindings maker // at the time of the eval might raise through here at which point the validation didn't yet happen. better // to just check again final boolean hasRebindings = msg.getArgs().containsKey(Tokens.ARGS_REBINDINGS); final String rebindingOrAliasParameter = hasRebindings ? Tokens.ARGS_REBINDINGS : Tokens.ARGS_ALIASES; if (msg.getArgs().containsKey(rebindingOrAliasParameter)) { final Map<String, String> aliases = (Map<String, String>) msg.getArgs() .get(rebindingOrAliasParameter); graphManager.rollback(new HashSet<>(aliases.values())); } else { graphManager.rollbackAll(); } } else { graphManager.rollbackAll(); } } }