Skip to content

Clarify the docs about the Package Manager #2147

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mkhludnev merged 1 commit into from
Dec 12, 2023
Merged

Clarify the docs about the Package Manager #2147

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 27 additions & 8 deletions ...solr-ref-guide/modules/configuration-guide/pages/package-manager-internals.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,9 +32,11 @@ This document contains an overview of those APIs.
== Classloaders

At the heart of the system, we have classloader isolation.
To achieve this, the system is simplified into two layered classloaders: the root classloader which has all the jars from Solr classpath.
This requires Solr node restart to change anything.
A set of named classloaders that inherit from the root classloader.
To achieve this, the system is simplified into two layered classloaders:

* The root classloader which has all the jars from Solr classpath. This requires Solr node restart to change anything.

* A set of named classloaders that inherit from the root classloader.
The life cycles of the named classloaders are tied to the package configuration in ZooKeeper.
As soon as the configuration is modified, the corresponding classloaders are reloaded and components are asked to reload.

Expand Down Expand Up @@ -95,7 +97,7 @@ The end points are:

Use the following steps to upload a jar signed with your public key:

. If you don't have a jar file with plugins, download a sample from github:
. If you don't have a jar file with plugins, download a sample from GitHub:
+
[source, bash,subs="attributes"]
----
Expand Down Expand Up @@ -144,12 +146,18 @@ A Package has the following attributes:
For every package/version in the packages definition, there is a unique `SolrResourceLoader` instance.
This is a child of the `CoreContainer` resource loader.

NOTE: Solr does not require that the version string follows any particular format -
it can be an arbitrary string or even an empty string.

=== packages.json

The package configurations live in a file called `packages.json` in ZooKeeper.
At any given moment we can have multiple versions of a given package in the package configuration.
The system will always use the latest version.
Versions are sorted by their numeric value and the highest is the latest.
Versions are sorted by their values in lexicographic order, and the largest string is considered to be the latest.

CAUTION: Lexicographic order for version strings means that for a package with versions *1.2.0*, *1.9.0*, *1.11.0*,
Copy link
Copy Markdown
Contributor

@epugh epugh Dec 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

REally? Can we please get a JIRA to fix this ;-).

Solr would pick *1.9.0* as the latest version.

For example:

Expand Down Expand Up @@ -187,7 +195,7 @@ Use the `delete` command to delete the highest version and choose the next highe
=== Using Multiple Versions in Parallel

We use `params.json` in the collection config to store a version of a package it uses.
By default it is the `$LATEST`.
By default, it is the `$LATEST`.

[source, json]
----
Expand All @@ -203,6 +211,15 @@ By default it is the `$LATEST`.
This is optional.
The default is `$LATEST`.

[NOTE]
====
The package version in `params.json` actually instructs Solr to pick the package with the
largest version that is not greater than the provided value.

So in the example above, if the only available versions for `mypkg` are *0.01* and *0.2*,
the version *0.01* will be used.
====

=== Workflow

* A new version of a package is added.
Expand Down Expand Up @@ -263,7 +280,7 @@ curl http://localhost:8983/solr/gettingstarted/config -H 'Content-type:applicati
"class": "mypkg:org.apache.solr.core.RuntimeLibReqHandler" }}'
----

. Verify that the component is created and it is using the correct version of the package to load classes from:
. Verify that the component is created, and it is using the correct version of the package to load classes from:
+
[source,bash]
----
Expand Down Expand Up @@ -394,7 +411,9 @@ Note that the `Version` value is `"2"`, which means the plugin is updated.
=== How to Avoid Automatic Upgrade

The default version used in any collection is always the latest.
However, setting a per-collection property in `params.json` ensures that the versions are always fixed irrespective of the new versions added.
However, setting a per-collection property in `params.json` ensures that the collection uses the same
package version (i.e., version *2.0*), irrespective of any versions larger than *2.0* that may be added to Solr
Copy link
Copy Markdown
Contributor

@epugh epugh Dec 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if we should say "later" or "more recent" than, versus "larger"

Copy link
Copy Markdown
Contributor Author

@AndreyBozhko AndreyBozhko Dec 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@epugh I thought of that, but felt that it could be misleading - because, for example, the current package version in Solr could be 2.11.0, and then the user uploads 2.9.0 (which isn't more recent semantically, but is "larger" lexicographically).

So without the params.json, the collection will be "upgraded" to use 2.9.0, - but if the version 2.11.0 is pinned, it will be used regardless of how the Solr compares the version strings.

at a later point.

[source,bash]
----
Expand Down