HIVE-19210: Create separate module for streaming ingest (Prasanth Jayachandran review...
[hive.git] / streaming / src / java / org / apache / hive / streaming / TransactionBatch.java
1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 */
18
19 package org.apache.hive.streaming;
20
21
22 import java.util.Collection;
23
24 /**
25 * Represents a set of Transactions returned by Hive. Supports opening, writing to
26 * and commiting/aborting each transaction. The interface is designed to ensure
27 * transactions in a batch are used up sequentially. To stream to the same HiveEndPoint
28 * concurrently, create separate StreamingConnections.
29 *
30 * Note on thread safety: At most 2 threads can run through a given TransactionBatch at the same
31 * time. One thread may call {@link #heartbeat()} and the other all other methods.
32 * Violating this may result in "out of sequence response".
33 *
34 */
35 public interface TransactionBatch {
36 enum TxnState {
37 INACTIVE("I"), OPEN("O"), COMMITTED("C"), ABORTED("A");
38
39 private final String code;
40 TxnState(String code) {
41 this.code = code;
42 };
43 public String toString() {
44 return code;
45 }
46 }
47
48 /**
49 * Activate the next available transaction in the current transaction batch.
50 * @throws StreamingException if not able to switch to next Txn
51 * @throws InterruptedException if call in interrupted
52 */
53 void beginNextTransaction() throws StreamingException, InterruptedException;
54
55 /**
56 * Get Id of currently open transaction.
57 * @return transaction id
58 */
59 Long getCurrentTxnId();
60
61
62 /**
63 * Get write Id mapping to currently open transaction.
64 * @return write id
65 */
66 Long getCurrentWriteId();
67
68 /**
69 * get state of current transaction.
70 */
71 TxnState getCurrentTransactionState();
72
73 /**
74 * Commit the currently open transaction.
75 * @throws StreamingException if there are errors committing
76 * @throws InterruptedException if call in interrupted
77 */
78 void commit() throws StreamingException, InterruptedException;
79
80 /**
81 * Abort the currently open transaction.
82 * @throws StreamingException if there are errors
83 * @throws InterruptedException if call in interrupted
84 */
85 void abort() throws StreamingException, InterruptedException;
86
87 /**
88 * Remaining transactions are the ones that are not committed or aborted or open.
89 * Current open transaction is not considered part of remaining txns.
90 * @return number of transactions remaining this batch.
91 */
92 int remainingTransactions();
93
94
95 /**
96 * Write record using RecordWriter.
97 * @param record the data to be written
98 * @throws StreamingException if there are errors when writing
99 * @throws InterruptedException if call in interrupted
100 */
101 void write(byte[] record) throws StreamingException, InterruptedException;
102
103 /**
104 * Write records using RecordWriter.
105 * @throws StreamingException if there are errors when writing
106 * @throws InterruptedException if call in interrupted
107 */
108 void write(Collection<byte[]> records) throws StreamingException, InterruptedException;
109
110
111 /**
112 * Issues a heartbeat to hive metastore on the current and remaining txn ids
113 * to keep them from expiring.
114 * @throws StreamingException if there are errors
115 */
116 void heartbeat() throws StreamingException;
117
118 /**
119 * Close the TransactionBatch.
120 * @throws StreamingException if there are errors closing batch
121 * @throws InterruptedException if call in interrupted
122 */
123 void close() throws StreamingException, InterruptedException;
124 boolean isClosed();
125 }