1 /*
2 * Tentackle - https://tentackle.org
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 of the License, or (at your option) any later version.
8 *
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, write to the Free Software
16 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17 */
18
19 package org.tentackle.dbms.trip;
20
21 import org.tentackle.common.Service;
22
23 import java.lang.annotation.Documented;
24 import java.lang.annotation.ElementType;
25 import java.lang.annotation.Retention;
26 import java.lang.annotation.RetentionPolicy;
27 import java.lang.annotation.Target;
28
29 /**
30 * Marks a class as a candidate for preloading its remote delegate.<br>
31 * Applicable to persistence implementations of entities and operations, i.e., all classes
32 * registered via {@link org.tentackle.dbms.Db#prepareRemoteDelegate}.
33 * <p>
34 * Remote delegates are created lazily, one roundtrip per class. For applications with a large
35 * entity model running on links with high latency, this may slow down the application startup
36 * substantially. Annotated classes are collected at build time and can be requested by the client
37 * in a single roundtrip via {@link org.tentackle.session.Session#preloadRemoteDelegates()}.
38 * <p>
39 * The annotation only makes a class a <em>candidate</em>: nothing is preloaded unless the
40 * application explicitly requests it, since not all sessions benefit from preloading.
41 * Annotate the classes used during startup, not the whole entity model.
42 * <p>
43 * Notice that preloading creates the delegate on the server, which invokes
44 * {@link RemoteDbDelegateImpl#initialize()}. Classes whose delegates change the state of the
45 * server session when created must not be annotated. {@code DbModificationTracker} is such
46 * an example: creating its delegate marks the session as the modification tracker's session.
47 *
48 * @see org.tentackle.session.Session#preloadRemoteDelegates()
49 */
50 @Documented
51 @Retention(RetentionPolicy.RUNTIME)
52 @Target(ElementType.TYPE)
53 @Service(PreloadRemoteDelegate.class) // the annotation itself serves as the service name
54 public @interface PreloadRemoteDelegate {
55 }