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,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.syncope.core.provisioning.api;
20
21 import java.util.List;
22 import java.util.Set;
23 import java.util.concurrent.atomic.AtomicReference;
24 import java.util.stream.Collectors;
25 import org.apache.syncope.core.persistence.api.dao.search.OrderByClause;
26 import org.apache.syncope.core.persistence.api.entity.ConnInstance;
27 import org.apache.syncope.core.provisioning.api.pushpull.ReconFilterBuilder;
28 import org.identityconnectors.framework.common.objects.Attribute;
29 import org.identityconnectors.framework.common.objects.AttributeDelta;
30 import org.identityconnectors.framework.common.objects.ConnectorObject;
31 import org.identityconnectors.framework.common.objects.ObjectClass;
32 import org.identityconnectors.framework.common.objects.ObjectClassInfo;
33 import org.identityconnectors.framework.common.objects.OperationOptions;
34 import org.identityconnectors.framework.common.objects.OperationOptionsBuilder;
35 import org.identityconnectors.framework.common.objects.SearchResult;
36 import org.identityconnectors.framework.common.objects.SortKey;
37 import org.identityconnectors.framework.common.objects.SyncDeltaBuilder;
38 import org.identityconnectors.framework.common.objects.SyncDeltaType;
39 import org.identityconnectors.framework.common.objects.SyncResultsHandler;
40 import org.identityconnectors.framework.common.objects.SyncToken;
41 import org.identityconnectors.framework.common.objects.Uid;
42 import org.identityconnectors.framework.common.objects.filter.Filter;
43 import org.identityconnectors.framework.spi.SearchResultsHandler;
44
45 /**
46 * Entry point for making requests on underlying connector bundles.
47 */
48 public interface Connector {
49
50 /**
51 * Authenticate user on a connector instance.
52 *
53 * @param username the name based credential for authentication
54 * @param password the password based credential for authentication
55 * @param options ConnId's OperationOptions
56 * @return Uid of the account that was used to authenticate
57 */
58 Uid authenticate(String username, String password, OperationOptions options);
59
60 /**
61 * Create user, group or any object on a connector instance.
62 *
63 * @param objectClass ConnId's object class
64 * @param attrs attributes for creation
65 * @param options ConnId's OperationOptions
66 * @param propagationAttempted if creation is actually performed (based on connector instance's capabilities)
67 * @return Uid for created object
68 */
69 Uid create(
70 ObjectClass objectClass,
71 Set<Attribute> attrs,
72 OperationOptions options,
73 AtomicReference<Boolean> propagationAttempted);
74
75 /**
76 * Update user, group or any object on a connector instance.
77 *
78 * @param objectClass ConnId's object class
79 * @param uid remote identifier
80 * @param attrs attributes for update
81 * @param options ConnId's OperationOptions
82 * @param propagationAttempted if creation is actually performed (based on connector instance's capabilities)
83 * @return Uid for updated object
84 */
85 Uid update(
86 ObjectClass objectClass,
87 Uid uid,
88 Set<Attribute> attrs,
89 OperationOptions options,
90 AtomicReference<Boolean> propagationAttempted);
91
92 /**
93 * Partial update user, group or any object on a connector instance.
94 *
95 * @param objectClass ConnId's object class
96 * @param uid remote identifier
97 * @param modifications attribute modifications to apply
98 * @param options ConnId's OperationOptions
99 * @param propagationAttempted if creation is actually performed (based on connector instance's capabilities)
100 * @return the applied modifications
101 */
102 Set<AttributeDelta> updateDelta(
103 ObjectClass objectClass,
104 Uid uid,
105 Set<AttributeDelta> modifications,
106 OperationOptions options,
107 AtomicReference<Boolean> propagationAttempted);
108
109 /**
110 * Delete user, group or any object on a connector instance.
111 *
112 * @param objectClass ConnId's object class
113 * @param uid user to be deleted
114 * @param options ConnId's OperationOptions
115 * @param propagationAttempted if deletion is actually performed (based on connector instance's capabilities)
116 */
117 void delete(
118 ObjectClass objectClass,
119 Uid uid,
120 OperationOptions options,
121 AtomicReference<Boolean> propagationAttempted);
122
123 /**
124 * Fetches all remote objects (for use during full reconciliation).
125 *
126 * @param objectClass ConnId's object class.
127 * @param handler to be used to handle deltas.
128 * @param options ConnId's OperationOptions.
129 */
130 default void fullReconciliation(ObjectClass objectClass, SyncResultsHandler handler, OperationOptions options) {
131 filteredReconciliation(objectClass, null, handler, options);
132 }
133
134 /**
135 * Fetches remote objects (for use during filtered reconciliation).
136 *
137 * @param objectClass ConnId's object class.
138 * @param filterBuilder reconciliation filter builder
139 * @param handler to be used to handle deltas.
140 * @param options ConnId's OperationOptions.
141 */
142 default void filteredReconciliation(
143 ObjectClass objectClass,
144 ReconFilterBuilder filterBuilder,
145 SyncResultsHandler handler,
146 OperationOptions options) {
147
148 Filter filter = null;
149 OperationOptions actualOptions = options;
150 if (filterBuilder != null) {
151 filter = filterBuilder.build(objectClass);
152 actualOptions = filterBuilder.build(objectClass, actualOptions);
153 }
154
155 search(objectClass, filter, new SearchResultsHandler() {
156
157 @Override
158 public void handleResult(final SearchResult result) {
159 // nothing to do
160 }
161
162 @Override
163 public boolean handle(final ConnectorObject object) {
164 return handler.handle(new SyncDeltaBuilder().
165 setObject(object).
166 setDeltaType(SyncDeltaType.CREATE_OR_UPDATE).
167 setToken(new SyncToken("")).
168 build());
169 }
170 }, actualOptions);
171 }
172
173 /**
174 * Sync remote objects from a connector instance.
175 *
176 * @param objectClass ConnId's object class
177 * @param token to be passed to the underlying connector
178 * @param handler to be used to handle deltas
179 * @param options ConnId's OperationOptions
180 */
181 void sync(ObjectClass objectClass, SyncToken token, SyncResultsHandler handler, OperationOptions options);
182
183 /**
184 * Read latest sync token from a connector instance.
185 *
186 * @param objectClass ConnId's object class.
187 * @return latest sync token
188 */
189 SyncToken getLatestSyncToken(ObjectClass objectClass);
190
191 /**
192 * Get remote object.
193 *
194 * @param objectClass ConnId's object class
195 * @param connObjectKey ConnId's key attribute
196 * @param ignoreCaseMatch whether match should be performed regardless of the value case
197 * @param options ConnId's OperationOptions
198 * @return ConnId's connector object for given uid
199 */
200 ConnectorObject getObject(
201 ObjectClass objectClass,
202 Attribute connObjectKey,
203 boolean ignoreCaseMatch,
204 OperationOptions options);
205
206 /**
207 * Search for remote objects.
208 *
209 * @param objectClass ConnId's object class
210 * @param filter search filter
211 * @param handler class responsible for working with the objects returned from the search; may be null.
212 * @param options ConnId's OperationOptions
213 * @return search result
214 */
215 SearchResult search(
216 ObjectClass objectClass,
217 Filter filter,
218 SearchResultsHandler handler,
219 OperationOptions options);
220
221 /**
222 * Search for remote objects.
223 *
224 * @param objectClass ConnId's object class
225 * @param filter search filter
226 * @param handler class responsible for working with the objects returned from the search; may be null.
227 * @param pageSize requested page results page size
228 * @param pagedResultsCookie an opaque cookie which is used by the connector to track its position in the set of
229 * query results
230 * @param orderBy the sort keys which should be used for ordering the {@link ConnectorObject} returned by
231 * search request
232 * @param options ConnId's OperationOptions
233 * @return search result
234 */
235 default SearchResult search(
236 ObjectClass objectClass,
237 Filter filter,
238 SearchResultsHandler handler,
239 int pageSize,
240 String pagedResultsCookie,
241 List<OrderByClause> orderBy,
242 OperationOptions options) {
243
244 OperationOptionsBuilder builder = new OperationOptionsBuilder().setPageSize(pageSize).setPagedResultsOffset(-1);
245 if (pagedResultsCookie != null) {
246 builder.setPagedResultsCookie(pagedResultsCookie);
247 }
248 builder.setSortKeys(orderBy.stream().
249 map(clause -> new SortKey(clause.getField(), clause.getDirection() == OrderByClause.Direction.ASC)).
250 collect(Collectors.toList()));
251
252 builder.setAttributesToGet(options.getAttributesToGet());
253
254 return search(objectClass, filter, handler, builder.build());
255 }
256
257 /**
258 * Builds metadata description of ConnId {@link ObjectClass}.
259 *
260 * @return metadata description of ConnId ObjectClass
261 */
262 Set<ObjectClassInfo> getObjectClassInfo();
263
264 /**
265 * Validate connector instance.
266 */
267 void validate();
268
269 /**
270 * Check connection.
271 */
272 void test();
273
274 /**
275 * Dispose of any resources associated with connector instance.
276 */
277 void dispose();
278
279 /**
280 * Getter for active connector instance.
281 *
282 * @return active connector instance.
283 */
284 ConnInstance getConnInstance();
285 }