|
18 | 18 | */ |
19 | 19 | package org.neo4j.driver; |
20 | 20 |
|
21 | | -import java.util.Map; |
22 | | - |
23 | 21 | /** |
24 | | - * Common interface for components that can execute Neo4j queries. |
25 | | - * |
26 | | - * <h2>Important notes on semantics</h2> |
27 | | - * <p> |
28 | | - * queries run in the same {@link QueryRunner} are guaranteed |
29 | | - * to execute in order, meaning changes made by one query will be seen |
30 | | - * by all subsequent queries in the same {@link QueryRunner}. |
31 | | - * <p> |
32 | | - * However, to allow handling very large results, and to improve performance, |
33 | | - * result streams are retrieved lazily from the network. |
34 | | - * This means that when any of {@link #run(Query)} |
35 | | - * methods return a result, the query has only started executing - it may not |
36 | | - * have completed yet. Most of the time, you will not notice this, because the |
37 | | - * driver automatically waits for queries to complete at specific points to |
38 | | - * fulfill its contracts. |
39 | | - * <p> |
40 | | - * Specifically, the driver will ensure all outstanding queries are completed |
41 | | - * whenever you: |
| 22 | + * An {@link AutoCloseable} extension of the {@link SimpleQueryRunner}. |
42 | 23 | * |
43 | | - * <ul> |
44 | | - * <li>Read from or discard a result, for instance via |
45 | | - * {@link Result#next()} or {@link Result#consume()} </li> |
46 | | - * <li>Explicitly commit/rollback a transaction using blocking {@link Transaction#close()} </li> |
47 | | - * <li>Close a session using blocking {@link Session#close()}</li> |
48 | | - * </ul> |
49 | | - * <p> |
50 | | - * As noted, most of the time, you will not need to consider this - your writes will |
51 | | - * always be durably stored as long as you either use the results, explicitly commit |
52 | | - * {@link Transaction transactions} or close the session you used using {@link Session#close()}. |
53 | | - * <p> |
54 | | - * While these semantics introduce some complexity, it gives the driver the ability |
55 | | - * to handle infinite result streams (like subscribing to events), significantly lowers |
56 | | - * the memory overhead for your application and improves performance. |
57 | | - * |
58 | | - * @see Session |
59 | | - * @see Transaction |
60 | 24 | * @since 1.0 |
61 | 25 | */ |
62 | | -public interface QueryRunner extends AutoCloseable |
| 26 | +public interface QueryRunner extends SimpleQueryRunner, AutoCloseable |
63 | 27 | { |
64 | | - /** |
65 | | - * Run a query and return a result stream. |
66 | | - * <p> |
67 | | - * This method takes a set of parameters that will be injected into the |
68 | | - * query by Neo4j. Using parameters is highly encouraged, it helps avoid |
69 | | - * dangerous cypher injection attacks and improves database performance as |
70 | | - * Neo4j can re-use query plans more often. |
71 | | - * <p> |
72 | | - * This particular method takes a {@link Value} as its input. This is useful |
73 | | - * if you want to take a map-like value that you've gotten from a prior result |
74 | | - * and send it back as parameters. |
75 | | - * <p> |
76 | | - * If you are creating parameters programmatically, {@link #run(String, Map)} |
77 | | - * might be more helpful, it converts your map to a {@link Value} for you. |
78 | | - * |
79 | | - * <h2>Example</h2> |
80 | | - * <pre class="doctest:QueryRunnerDocIT#parameterTest"> |
81 | | - * {@code |
82 | | - * |
83 | | - * Result result = session.run( "MATCH (n) WHERE n.name = $myNameParam RETURN (n)", |
84 | | - * Values.parameters( "myNameParam", "Bob" ) ); |
85 | | - * } |
86 | | - * </pre> |
87 | | - * |
88 | | - * @param query text of a Neo4j query |
89 | | - * @param parameters input parameters, should be a map Value, see {@link Values#parameters(Object...)}. |
90 | | - * @return a stream of result values and associated metadata |
91 | | - */ |
92 | | - Result run(String query, Value parameters ); |
93 | | - |
94 | | - /** |
95 | | - * Run a query and return a result stream. |
96 | | - * <p> |
97 | | - * This method takes a set of parameters that will be injected into the |
98 | | - * query by Neo4j. Using parameters is highly encouraged, it helps avoid |
99 | | - * dangerous cypher injection attacks and improves database performance as |
100 | | - * Neo4j can re-use query plans more often. |
101 | | - * <p> |
102 | | - * This version of run takes a {@link Map} of parameters. The values in the map |
103 | | - * must be values that can be converted to Neo4j types. See {@link Values#parameters(Object...)} for |
104 | | - * a list of allowed types. |
105 | | - * |
106 | | - * <h2>Example</h2> |
107 | | - * <pre class="doctest:QueryRunnerDocIT#parameterTest"> |
108 | | - * {@code |
109 | | - * |
110 | | - * Map<String, Object> parameters = new HashMap<String, Object>(); |
111 | | - * parameters.put("myNameParam", "Bob"); |
112 | | - * |
113 | | - * Result result = session.run( "MATCH (n) WHERE n.name = $myNameParam RETURN (n)", |
114 | | - * parameters ); |
115 | | - * } |
116 | | - * </pre> |
117 | | - * |
118 | | - * @param query text of a Neo4j query |
119 | | - * @param parameters input data for the query |
120 | | - * @return a stream of result values and associated metadata |
121 | | - */ |
122 | | - Result run(String query, Map<String,Object> parameters ); |
123 | | - |
124 | | - /** |
125 | | - * Run a query and return a result stream. |
126 | | - * <p> |
127 | | - * This method takes a set of parameters that will be injected into the |
128 | | - * query by Neo4j. Using parameters is highly encouraged, it helps avoid |
129 | | - * dangerous cypher injection attacks and improves database performance as |
130 | | - * Neo4j can re-use query plans more often. |
131 | | - * <p> |
132 | | - * This version of run takes a {@link Record} of parameters, which can be useful |
133 | | - * if you want to use the output of one query as input for another. |
134 | | - * |
135 | | - * @param query text of a Neo4j query |
136 | | - * @param parameters input data for the query |
137 | | - * @return a stream of result values and associated metadata |
138 | | - */ |
139 | | - Result run(String query, Record parameters ); |
140 | | - |
141 | | - /** |
142 | | - * Run a query and return a result stream. |
143 | | - * |
144 | | - * @param query text of a Neo4j query |
145 | | - * @return a stream of result values and associated metadata |
146 | | - */ |
147 | | - Result run(String query ); |
148 | | - |
149 | | - /** |
150 | | - * Run a query and return a result stream. |
151 | | - * <h2>Example</h2> |
152 | | - * <pre class="doctest:QueryRunnerDocIT#queryObjectTest"> |
153 | | - * {@code |
154 | | - * |
155 | | - * Query query = new Query( "MATCH (n) WHERE n.name = $myNameParam RETURN n.age" ); |
156 | | - * Result result = session.run( query.withParameters( Values.parameters( "myNameParam", "Bob" ) ) ); |
157 | | - * } |
158 | | - * </pre> |
159 | | - * |
160 | | - * @param query a Neo4j query |
161 | | - * @return a stream of result values and associated metadata |
162 | | - */ |
163 | | - Result run(Query query); |
164 | 28 | } |
0 commit comments