apache-ignite

1
// Licensed to the Apache Software Foundation (ASF) under one or more
2
// contributor license agreements.  See the NOTICE file distributed with
3
// this work for additional information regarding copyright ownership.
4
// The ASF licenses this file to You under the Apache License, Version 2.0
5
// (the "License"); you may not use this file except in compliance with
6
// the License.  You may obtain a copy of the License at
7
//
8
// http://www.apache.org/licenses/LICENSE-2.0
9
//
10
// Unless required by applicable law or agreed to in writing, software
11
// distributed under the License is distributed on an "AS IS" BASIS,
12
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
// See the License for the specific language governing permissions and
14
// limitations under the License.
15
= Peer Class Loading
16

17
== Overview
18

19
Peer class loading refers to loading classes from a local node where they are defined to remote nodes.
20
With peer class loading enabled, you don't have to manually deploy your Java code on each node in the cluster and re-deploy it each time it changes.
21
Ignite automatically loads the classes from the node where they are defined to the nodes where they are used.
22

23
[CAUTION]
24
====
25
[discrete]
26
=== Automatic Assemblies Loading in .NET
27
If you develop C# and .NET applications, then refer to the link:net-specific/net-remote-assembly-loading[Remote Assembly Loading]
28
page for details on how to set up and use the peer-class-loading feature with that type of applications.
29
====
30

31
For example, when link:key-value-api/using-cache-queries[querying data] with a custom transformer, you just need to define your tasks on the client node that initiates the computation, and Ignite will upload the classes to the server nodes.
32

33
When enabled, peer class loading is used to deploy the following classes:
34

35
* Tasks and jobs submitted via the link:distributed-computing/distributed-computing[compute interface].
36
* Transformers and filters used with link:key-value-api/using-cache-queries[cache queries] and link:key-value-api/continuous-queries[continuous queries].
37
* Stream transformers, receivers and visitors used with link:data-streaming#data-streamers[data streamers].
38
* link:distributed-computing/collocated-computations#entry-processor[Entry processors].
39

40
When defining the classes listed above, we recommend that each class is created as either a separate class or inner static class and not as a lambda or anonymous inner class. Non-static inner classes are serialized together with its enclosing class. If some fields of the enclosing class cannot be serialized, you will get serialization exceptions.
41

42
[IMPORTANT]
43
====
44
The peer class loading functionality does not deploy the key and object classes of the entries stored in caches.
45
====
46

47
[WARNING]
48
====
49
The peer class loading functionality allows any client to deploy custom code to the cluster. If you want to use it in production environments, make sure only authorized clients have access to the cluster.
50
====
51

52

53
This is what happens when a class is required on remote nodes:
54

55
* Ignite checks if the class is available in the local classpath, i.e. if it was loaded during system initialization, and if it was, it is returned. No class loading from a peer node takes place in this case.
56
* If the class is not available locally, then a request for the class definition is sent to the originating node. The originating node sends the class's byte-code and the class is loaded on the worker node. This happens once per class. When the class definition is loaded on a node, it does not have to be loaded again.
57

58
[NOTE]
59
====
60
[discrete]
61
=== Deploying 3rd Party Libraries
62
When utilizing peer class loading, you should be aware of the libraries that get loaded from peer nodes vs. libraries that are already available locally in the class path.
63
We suggest you should include all 3rd party libraries into the class path of every node.
64
This can be achieved by copying your JAR files into the `{IGNITE_HOME}/libs` folder.
65
This way you do not transfer megabytes of 3rd party classes to remote nodes every time you change a line of code.
66
====
67

68

69
== Enabling Peer Class Loading
70

71
Here is how you can configure peer class loading:
72

73

74
[tabs]
75
--
76
tab:XML[]
77
[source,xml]
78
----
79
include::code-snippets/xml/peer-class-loading.xml[tags=ignite-config;!discovery, indent=0]
80
----
81
tab:Java[]
82
[source,java]
83
----
84
include::{javaCodeDir}/PeerClassLoading.java[tags=configure, indent=0]
85
----
86

87
tab:C#/.NET[]
88
[source,csharp]
89
----
90
include::code-snippets/dotnet/PeerClassLoading.cs[tag=enable,indent=0]
91
----
92

93
tab:C++[unsupported]
94
--
95

96

97
The following table describes parameters related to peer class loading.
98

99
[cols="30%,60%,10%",opts="header,width=100%"]
100
|===
101
|Parameter| Description | Default value
102

103
|`peerClassLoadingEnabled`| Enables/disables peer class loading. | `false`
104
|`deploymentMode` | The peer class loading mode. | `SHARED`
105

106
| `peerClassLoadingExecutorService` | Configures a thread pool to be used for peer class loading. If not configured, a default pool is used.  | `null`
107
| `peerClassLoadingExecutorServiceShutdown` |Peer class loading executor service shutdown flag. If the flag is set to `true`, the peer class loading thread pool is forcibly shut down when the node stops. | `true`
108
|`peerClassLoadingLocalClassPathExclude` |List of packages in the system class path that should be P2P loaded even if they exist locally. | `null`
109

110
|`peerClassLoadingMissedResourcesCacheSize`| Size of missed resources cache. Set to 0 to avoid caching of missing resources. | 100
111

112
|===
113

114

115

116
== Peer Class Loading Modes
117

118
=== PRIVATE and ISOLATED
119
Classes deployed within the same class loader on the master node still share the same class loader remotely on worker nodes.
120
However, the tasks deployed from different master nodes does not share the same class loader on worker nodes.
121
This is useful in development environments when different developers can be working on different versions of the same classes.
122
There is no difference between `PRIVATE` and `ISOLATED` deployment modes since the `@UserResource` annotation has been removed.
123
Both constants were kept for backward-compatibility reasons and one of them is likely to be removed in a future major release.
124

125
In this mode, classes get un-deployed when the master node leaves the cluster.
126

127
=== SHARED
128

129
This is the default deployment mode.
130
In this mode, classes from different master nodes with the same user version share the same class loader on worker nodes.
131
Classes are un-deployed when all master nodes leave the cluster or the user version changes.
132
This mode allows classes coming from different master nodes to share the same instances of user resources on remote nodes (see below).
133
This method is specifically useful in production as, in comparison to `ISOLATED` mode which has a scope of a single class loader on a single master node, `SHARED` mode broadens the deployment scope to all master nodes.
134

135
In this mode, classes get un-deployed when all the master nodes leave the cluster.
136

137
=== CONTINUOUS
138
In `CONTINUOUS` mode, the classes do not get un-deployed when master nodes leave the cluster.
139
Un-deployment only happens when a class user version changes.
140
The advantage of this approach is that it allows tasks coming from different master nodes to share the same instances of user resources on worker nodes.
141
This allows the tasks executing on worker nodes to reuse, for example, the same instances of connection pools or caches.
142
When using this mode, you can start up multiple stand-alone worker nodes, define user resources on the master nodes, and have them initialized once on worker nodes regardless of which master node they came from.
143
In comparison to the `ISOLATED` deployment mode which has a scope of a single class loader on a single master node, `CONTINUOUS` mode broadens the deployment scope to all master nodes which is specifically useful in production.
144

145
In this mode, classes do not get un-deployed even if all the master nodes leave the cluster.
146

147
== Un-Deployment and User Versions
148

149
The classes deployed with peer class loading have their own lifecycle. On certain events (when the master node leaves or the user version changes, depending on deployment mode), the class information is un-deployed from the cluster: the class definition is erased from all nodes and the user resources linked with that class definition are also optionally erased (again, depending on deployment mode).
150

151
User version comes into play whenever you want to redeploy classes deployed in `SHARED` or `CONTINUOUS` modes.
152
By default, Ignite automatically detects if the class loader has changed or a node is restarted.
153
However, if you would like to change and redeploy the code on a subset of nodes, or in the case of `CONTINUOUS` mode, kill every living deployment, you should change the user version.
154
User version is specified in the `META-INF/ignite.xml` file of your class path as follows:
155

156
[source, xml]
157
-------------------------------------------------------------------------------
158
<!-- User version. -->
159
<bean id="userVersion" class="java.lang.String">
160
    <constructor-arg value="0"/>
161
</bean>
162
-------------------------------------------------------------------------------
163

164
By default, all Ignite startup scripts (ignite.sh or ignite.bat) pick up the user version from the `IGNITE_HOME/config/userversion` folder.
165
Usually, you just need to update the user version under that folder.
166
However, in case of GAR or JAR deployment, you should remember to provide the `META-INF/ignite.xml` file with the desired user version in it.
167