1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
// Copyright Yahoo. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root.
package com.yahoo.documentapi;
import com.yahoo.document.DocumentTypeManager;
import com.yahoo.document.DocumentTypeManagerConfigurer;
import com.yahoo.document.select.parser.ParseException;
import com.yahoo.config.subscription.ConfigSubscriber;
import com.yahoo.documentapi.messagebus.MessageBusDocumentAccess;
/**
* <p>This is the starting point of the <b>document api</b>. This api provides
* access to documents in a document repository. The document api contains four
* separate access types: </p>
*
* <ul>
* <li><b>Synchronous random access</b> - provided by {@link SyncSession},
* allows simple access where throughput is not a concern.
* <li><b>Asynchronous random access</b> - provided by {@link AsyncSession},
* allows document repository writes and random access with high throughput.
* <li><b>Visiting</b> - provided by {@link VisitorSession}, allows a set of
* documents to be accessed in an order decided by the document repository. This
* allows much higher read throughput than random access.
* <li><b>Subscription</b> - provided by {@link SubscriptionSession}, allows
* changes to a defined set of documents in the repository to be
* visited.
* </ul>
*
* <p>This class is the factory for creating the four session types mentioned above.</p>
*
* <p>There may be multiple implementations of the document api classes. If
* default configuration is sufficient, simply inject a {@code DocumentAccess} to
* obtain a running document access. If you instead create a concrete implementation, note that
* there are running threads within an access object, so you must shut it down when done.</p>
*
* <p>An implementation of the Document Api may support just a subset of the
* access types defined in this interface. For example, some document
* repositories, like indexes, are <i>write only</i>. Others may support random
* access, but not visiting and subscription. Any method which is not supported
* by the underlying implementation will throw UnsupportedOperationException.</p>
*
* <p>Access to this class is thread-safe.</p>
*
* @author bratseth
* @author Einar Rosenvinge
* @author Simon Thoresen Hult
*/
public abstract class DocumentAccess {
private final DocumentTypeManager documentTypeManager;
private final ConfigSubscriber documentTypeConfigSubscriber;
/**
* This is a convenience method to return a document access object when running
* outside of a Vespa application container, with all default parameter values.
* The client that calls this method is also responsible for shutting the object
* down when done. If an error occurred while attempting to create such an object,
* this method will throw an exception.
* This document access requires new config subscriptions to be set up, which should
* be avoided in application containers, but is suitable for, e.g., CLIs.
*
* @return a running document access object with all default configuration
*/
public static DocumentAccess createForNonContainer() {
return new MessageBusDocumentAccess();
}
/**
* Constructs a new document access object.
*
* @param params the parameters to use for setup
*/
protected DocumentAccess(DocumentAccessParams params) {
if (params.documentmanagerConfig().isPresent()) { // our config has been injected into the creator
documentTypeManager = new DocumentTypeManager(params.documentmanagerConfig().get());
documentTypeConfigSubscriber = null;
}
else { // fallback to old style subscription — this should be avoided
documentTypeManager = new DocumentTypeManager();
documentTypeConfigSubscriber = DocumentTypeManagerConfigurer.configure(documentTypeManager, params.getDocumentManagerConfigId());
}
}
/**
* Returns a session for synchronous document access. Use this for simple access.
*
* @param parameters the parameters of this sync session
* @return a session to use for synchronous document access
* @throws UnsupportedOperationException if this access implementation does not support synchronous access
* @throws RuntimeException if an error prevented the session from being created.
*/
public abstract SyncSession createSyncSession(SyncParameters parameters);
/**
* Returns a session for asynchronous document access. Use this if high operation throughput is required.
*
* @param parameters the parameters of this async session.
* @return a session to use for asynchronous document access.
* @throws UnsupportedOperationException if this access implementation does not support asynchronous access.
* @throws RuntimeException if an error prevented the session from being created
*/
public abstract AsyncSession createAsyncSession(AsyncParameters parameters);
/**
* Run a visitor with the given visitor parameters, and get the result back here.
*
* @param parameters The parameters of this visitor session.
* @return a session used to track progress of the visitor and get the actual data returned.
* @throws UnsupportedOperationException if this access implementation does not support visiting
* @throws RuntimeException if an error prevented the session from being created
* @throws ParseException if the document selection string could not be parsed
*/
public abstract VisitorSession createVisitorSession(VisitorParameters parameters) throws ParseException;
/**
* Creates a destination session for receiving data from visiting.
* The visitor must be started and progress tracked through a visitor session.
*
* @param parameters the parameters of this visitor destination session
* @return a session used to get the actual data returned
* @throws UnsupportedOperationException if this access implementation does not support visiting.
*/
public abstract VisitorDestinationSession createVisitorDestinationSession(VisitorDestinationParameters parameters);
/**
* Creates a subscription and returns a session for getting data from it.
* Use this to get document operations being done by other parties.
*
* @param parameters The parameters of this subscription session
* @return a session to use for document subscription
* @throws UnsupportedOperationException if this access implementation does not support subscription
* @throws RuntimeException if an error prevented the session from being created
*/
public abstract SubscriptionSession createSubscription(SubscriptionParameters parameters);
/**
* Returns a session for document subscription. Use this to get document operations being done by other parties.
*
* @param parameters the parameters of this subscription session
* @return a session to use for document subscription
* @throws UnsupportedOperationException if this access implementation does not support subscription
* @throws RuntimeException if an error prevented the session from being created
*/
public abstract SubscriptionSession openSubscription(SubscriptionParameters parameters);
/**
* Shuts down the underlying sessions used by this DocumentAccess;
* subsequent use of this DocumentAccess will throw unspecified exceptions, depending on implementation.
* Classes overriding this must call super.shutdown().
*/
public void shutdown() {
if (documentTypeConfigSubscriber != null)
documentTypeConfigSubscriber.close();
}
/** Returns the {@link DocumentTypeManager} used by this DocumentAccess. */
public DocumentTypeManager getDocumentTypeManager() { return documentTypeManager; }
}
|
