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

== Overview

Peer class loading refers to loading classes from a local node where they are defined to remote nodes.
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.
Ignite automatically loads the classes from the node where they are defined to the nodes where they are used.

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

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

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

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

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.

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

[WARNING]
====
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.
====


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

* 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.
* 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.

[NOTE]
====
[discrete]
=== Deploying 3rd Party Libraries
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.
We suggest you should include all 3rd party libraries into the class path of every node.
This can be achieved by copying your JAR files into the `{IGNITE_HOME}/libs` folder.
This way you do not transfer megabytes of 3rd party classes to remote nodes every time you change a line of code.
====


== Enabling Peer Class Loading

Here is how you can configure peer class loading:


[tabs]
--
tab:XML[]
[source,xml]
----
include::code-snippets/xml/peer-class-loading.xml[tags=ignite-config;!discovery, indent=0]
----
tab:Java[]
[source,java]
----
include::{javaCodeDir}/PeerClassLoading.java[tags=configure, indent=0]
----

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

tab:C++[unsupported]
--


The following table describes parameters related to peer class loading.

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

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

| `peerClassLoadingExecutorService` | Configures a thread pool to be used for peer class loading. If not configured, a default pool is used.  | `null`
| `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`
|`peerClassLoadingLocalClassPathExclude` |List of packages in the system class path that should be P2P loaded even if they exist locally. | `null`

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

|===


== Peer Class Loading Modes

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

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

=== SHARED

This is the default deployment mode.
In this mode, classes from different master nodes with the same user version share the same class loader on worker nodes.
Classes are un-deployed when all master nodes leave the cluster or the user version changes.
This mode allows classes coming from different master nodes to share the same instances of user resources on remote nodes (see below).
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.

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

=== CONTINUOUS
In `CONTINUOUS` mode, the classes do not get un-deployed when master nodes leave the cluster.
Un-deployment only happens when a class user version changes.
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.
This allows the tasks executing on worker nodes to reuse, for example, the same instances of connection pools or caches.
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.
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.

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

== Un-Deployment and User Versions

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).

User version comes into play whenever you want to redeploy classes deployed in `SHARED` or `CONTINUOUS` modes.
By default, Ignite automatically detects if the class loader has changed or a node is restarted.
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.
User version is specified in the `META-INF/ignite.xml` file of your class path as follows:

[source, xml]
-------------------------------------------------------------------------------
<!-- User version. -->
<bean id="userVersion" class="java.lang.String">
    <constructor-arg value="0"/>
</bean>
-------------------------------------------------------------------------------

By default, all Ignite startup scripts (ignite.sh or ignite.bat) pick up the user version from the `IGNITE_HOME/config/userversion` folder.
Usually, you just need to update the user version under that folder.
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.