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.pushpull;
20
21 import java.util.Set;
22 import org.apache.syncope.common.lib.request.AnyCR;
23 import org.apache.syncope.common.lib.request.AnyUR;
24 import org.apache.syncope.common.lib.to.EntityTO;
25 import org.apache.syncope.common.lib.to.LinkedAccountTO;
26 import org.apache.syncope.common.lib.to.OrgUnit;
27 import org.apache.syncope.common.lib.to.Provision;
28 import org.apache.syncope.common.lib.to.ProvisioningReport;
29 import org.apache.syncope.common.lib.to.RealmTO;
30 import org.identityconnectors.framework.common.objects.SyncDelta;
31 import org.quartz.JobExecutionException;
32
33 /**
34 * Interface for actions to be performed during pull.
35 * All methods can throw {@link IgnoreProvisionException} to make the current any object ignored by the pull
36 * process.
37 */
38 public interface PullActions extends ProvisioningActions {
39
40 /**
41 * Return additional attributes to include in the result from the underlying connector.
42 *
43 * @param profile profile of the pull being executed.
44 * @param orgUnit Realm provisioning information
45 * @return additional attributes to include in the result from the underlying connector
46 */
47 default Set<String> moreAttrsToGet(ProvisioningProfile<?, ?> profile, OrgUnit orgUnit) {
48 return Set.of();
49 }
50
51 /**
52 * Return additional attributes to include in the result from the underlying connector.
53 *
54 * @param profile profile of the pull being executed.
55 * @param provision Any provisioning information
56 * @return additional attributes to include in the result from the underlying connector
57 */
58 default Set<String> moreAttrsToGet(ProvisioningProfile<?, ?> profile, Provision provision) {
59 return Set.of();
60 }
61
62 /**
63 * Pre-process the pull information received by the underlying connector, before any internal activity occurs.
64 *
65 * @param profile profile of the pull being executed.
66 * @param delta retrieved pull information
67 * @return pull information, possibly altered.
68 */
69 default SyncDelta preprocess(ProvisioningProfile<?, ?> profile, SyncDelta delta) {
70 return delta;
71 }
72
73 /**
74 * Action to be executed before to create a pulled entity locally.
75 * The entity is created locally upon pull in case of the un-matching rule
76 * {@link org.apache.syncope.common.lib.types.UnmatchingRule#PROVISION} (default un-matching rule) is applied.
77 *
78 * @param profile profile of the pull being executed.
79 * @param delta retrieved pull information
80 * @param createReq create request
81 * @throws JobExecutionException in case of generic failure
82 */
83 default void beforeProvision(
84 ProvisioningProfile<?, ?> profile,
85 SyncDelta delta,
86 AnyCR createReq) throws JobExecutionException {
87 }
88
89 /**
90 * Action to be executed before locally creating a linked account.
91 *
92 * @param profile profile of the pull being executed.
93 * @param delta retrieved pull information
94 * @param linkedAccount create request
95 * @throws JobExecutionException in case of generic failure
96 */
97 default void beforeProvision(
98 ProvisioningProfile<?, ?> profile,
99 SyncDelta delta,
100 LinkedAccountTO linkedAccount) throws JobExecutionException {
101 }
102
103 /**
104 * Action to be executed before to create a pulled realm locally.
105 * The realm is created locally upon pull in case of the un-matching rule
106 * {@link org.apache.syncope.common.lib.types.UnmatchingRule#PROVISION} (default un-matching rule) is applied.
107 *
108 * @param profile profile of the pull being executed.
109 * @param delta retrieved pull information
110 * @param realm realm
111 * @throws JobExecutionException in case of generic failure
112 */
113 default void beforeProvision(
114 ProvisioningProfile<?, ?> profile,
115 SyncDelta delta,
116 RealmTO realm) throws JobExecutionException {
117 }
118
119 /**
120 * Action to be executed before creating (and linking to the resource) a pulled entity locally.
121 * The entity is created locally and linked to the pulled resource upon pull in case of the
122 * un-matching rule {@link org.apache.syncope.common.lib.types.UnmatchingRule#ASSIGN} is applied.
123 *
124 * @param profile profile of the pull being executed.
125 * @param delta retrieved pull information
126 * @param createReq create request
127 * @throws JobExecutionException in case of generic failure
128 */
129 default void beforeAssign(
130 ProvisioningProfile<?, ?> profile,
131 SyncDelta delta,
132 AnyCR createReq) throws JobExecutionException {
133 }
134
135 /**
136 * Action to be executed before locally creating a linked account.
137 *
138 * @param profile profile of the pull being executed.
139 * @param delta retrieved pull information
140 * @param linkedAccount linked account
141 * @throws JobExecutionException in case of generic failure
142 */
143 default void beforeAssign(
144 ProvisioningProfile<?, ?> profile,
145 SyncDelta delta,
146 LinkedAccountTO linkedAccount) throws JobExecutionException {
147 }
148
149 /**
150 * Action to be executed before creating (and linking to the resource) a pulled realm locally.
151 * The realm is created locally and linked to the pulled resource upon pull in case of the
152 * un-matching rule {@link org.apache.syncope.common.lib.types.UnmatchingRule#ASSIGN} is applied.
153 *
154 * @param profile profile of the pull being executed.
155 * @param delta retrieved pull information
156 * @param realm realm
157 * @throws JobExecutionException in case of generic failure
158 */
159 default void beforeAssign(
160 ProvisioningProfile<?, ?> profile,
161 SyncDelta delta,
162 RealmTO realm) throws JobExecutionException {
163 }
164
165 /**
166 * Action to be executed before unlinking resource from the pulled entity and de-provisioning.
167 * The entity is unlinked and de-provisioned from the pulled resource upon pull in case of the
168 * matching rule {@link org.apache.syncope.common.lib.types.MatchingRule#UNASSIGN} is applied.
169 *
170 * @param profile profile of the pull being executed.
171 * @param delta retrieved pull information
172 * @param entity entity
173 * @throws JobExecutionException in case of generic failure
174 */
175 default void beforeUnassign(
176 ProvisioningProfile<?, ?> profile,
177 SyncDelta delta,
178 EntityTO entity) throws JobExecutionException {
179 }
180
181 /**
182 * Action to be executed before de-provisioning action only.
183 * The entity is de-provisioned (without unlinking) from the pulled resource upon pull in case of
184 * the matching rule {@link org.apache.syncope.common.lib.types.MatchingRule#DEPROVISION} is applied.
185 *
186 * @param profile profile of the pull being executed.
187 * @param delta retrieved pull information
188 * @param entity entity
189 * @throws JobExecutionException in case of generic failure
190 */
191 default void beforeDeprovision(
192 ProvisioningProfile<?, ?> profile,
193 SyncDelta delta,
194 EntityTO entity) throws JobExecutionException {
195 }
196
197 /**
198 * Action to be executed before unlinking resource from the pulled entity.
199 * The entity is unlinked (without de-provisioning) from the pulled resource upon pull in case of
200 * the matching rule {@link org.apache.syncope.common.lib.types.MatchingRule#UNLINK} is applied.
201 *
202 * @param profile profile of the pull being executed.
203 * @param delta retrieved pull information
204 * @param entity entity
205 * @throws JobExecutionException in case of generic failure
206 */
207 default void beforeUnlink(
208 ProvisioningProfile<?, ?> profile,
209 SyncDelta delta,
210 EntityTO entity) throws JobExecutionException {
211 }
212
213 /**
214 * Action to be executed before linking resource to the pulled entity.
215 * The entity is linked (without updating) to the pulled resource upon pull in case of
216 * the matching rule {@link org.apache.syncope.common.lib.types.MatchingRule#LINK} is applied.
217 *
218 * @param profile profile of the pull being executed.
219 * @param delta retrieved pull information
220 * @param entity entity
221 * @throws JobExecutionException in case of generic failure
222 */
223 default void beforeLink(
224 ProvisioningProfile<?, ?> profile,
225 SyncDelta delta,
226 EntityTO entity) throws JobExecutionException {
227 }
228
229 /**
230 * Action to be executed before to update a pulled entity locally.
231 * The entity is updated upon pull in case of the matching rule
232 * {@link org.apache.syncope.common.lib.types.MatchingRule#UPDATE} (default matching rule) is applied.
233 *
234 * @param profile profile of the pull being executed.
235 * @param delta retrieved pull information
236 * @param entity entity
237 * @param anyUR modification
238 * @throws JobExecutionException in case of generic failure.
239 */
240 default void beforeUpdate(
241 ProvisioningProfile<?, ?> profile,
242 SyncDelta delta,
243 EntityTO entity,
244 AnyUR anyUR) throws JobExecutionException {
245 }
246
247 /**
248 * Action to be executed before to delete a pulled entity locally.
249 *
250 * @param profile profile of the pull being executed.
251 * @param delta retrieved pull information
252 * @param entity entity
253 * @throws JobExecutionException in case of generic failure
254 */
255 default void beforeDelete(
256 ProvisioningProfile<?, ?> profile,
257 SyncDelta delta,
258 EntityTO entity) throws JobExecutionException {
259 }
260
261 /**
262 * Action to be executed after each local entity pull.
263 *
264 * @param profile profile of the pull being executed.
265 * @param delta retrieved pull information (may be modified by beforeProvisionTO / beforeUpdate /
266 * beforeDelete)
267 * @param entity entity
268 * @param result global pull results at the current pull step
269 * @throws JobExecutionException in case of generic failure
270 */
271 default void after(
272 ProvisioningProfile<?, ?> profile,
273 SyncDelta delta,
274 EntityTO entity,
275 ProvisioningReport result) throws JobExecutionException {
276
277 // do nothing
278 }
279
280 /**
281 * Action to be executed in case an exception is thrown during pull.
282 *
283 * @param profile profile of the pull being executed.
284 * @param delta retrieved pull information (may be modified by beforeProvisionTO / beforeUpdate /
285 * beforeDelete)
286 * @param e the exception thrown
287 * @return an instance of the given exception type is that is to be thrown; {@code NULL} otherwise
288 * @throws JobExecutionException in case of generic failure
289 */
290 default IgnoreProvisionException onError(
291 ProvisioningProfile<?, ?> profile,
292 SyncDelta delta,
293 Exception e) throws JobExecutionException {
294
295 return null;
296 }
297 }