1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
|
~~ 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.
---
Offline Mode Design
---
John Casey
---
08-April-2005
---
Offline Mode Design
* UPDATE: 18-April-2005
We cannot take the approach outlined below of detecting which remote
repositories are "really" offline, since offline mode is more of a behavior,
and this will lead to counter-intuitive results. A different feature may exist
unimplemented, which is to detect when the network is down and provide better
feedback for that case. However, when offline mode is declared, nothing
earmarked as remote should be accessed, regardless of whether it is actually
a physically local resource.
NOTE: One side-effect of this design change is that all offline-mode code can
be isolated to maven-core, maven-plugin-descriptor, and [possibly]
maven-artifact. Usage of maven-wagon will be determined by an offline-aware
manager.
* Assumptions: What is Offline?
For the purposes of determining the areas sensitive to offline status,
it is definitely useful to define what the offline state really means.
[[1]] This is obvious, but the network/internet is unavailable.
[[2]] Localhost (127.0.0.1) may also be unavailable if the whole
network stack is offline.
[[3]] "Remote" repositories referenced using the file:// protocol may
be available. However, if that file:// url references a
file-share, as in the case of an NFS or SMB mount, that will
be unavailable.
So, offline mode has several implications, some of which may not be
altogether obvious:
* Localhost may be unavailable. Therefore, even locally installed
server processes which work by conversing over a port may fail.
* Not all "remote" repositories will fail. Specifically, if the remote
repo uses the file:// protocol, and it doesn't refer to a shared
filesystem, it will continue to be available.
The question remaining is: Which level of offline mode will we support? It
seems reasonable to assume that users will be able to tell when localhost is
not active (in most cases, localhost should be available, even if the rest of
the network is not). Therefore, let's concentrate on the state where no
network <beyond localhost> exists, and leave the more extreme state to users
to diagnose and correct as necessary.
* Why is Offline Mode Important?
Offline mode is essential for breaking the requirement that m2 operate in a
network-connected environment. It means legitimizing a development environment
in which there is no network connection, and providing a robust m2 service
offering in such circumstances. Introduction of offline mode allows m2 to
anticipate the inevitable network failures that accompany being physically
disconnected from the network, and adjust it's behavior accordingly.
It is more than simply understanding that m2 cannot go and check for the
latest version of some snapshot artifact. If m2 is offline, SCM operations
cannot succeed; no artifact downloads can take place, regardless of whether
they are snapshot versions; artifact deployment cannot take place; certain
types of tests cannot be setup, since the container used to run them cannot be
reached or started.
All of these operations will produce their own unique errors in the absence of
a coordinated offline strategy. In addition, efforts to unite these failing
behaviors behind a consistent user interface is much, much more difficult if
the system can't tell whether it has access to the network required by these
operations.
Offline mode really means anticipating a lack of network connectivity, and as
a result turning off certain services provided by m2 and providing a coherent
way of predicting and reporting when network-related failures will take place.
It means warning users that since the network is missing, certain features and
operations will be unavailable, rather than simply waiting for those
operations to fail, then trying to help users decipher the error messages they
get as a result.
* Implications for Resolution
** Dependency Resolution
This one is obvious...we only have access to the repositories using
the file:// protocol and living on a truly local filesystem when
offline.
** Plugin Resolution
This is similar to dependency resolution. Plugin repositories not
using file:// or not residing on a local (not shared) filesystem will
be unavailable.
* Implications for Mojo Execution
** Deployment mojos
The concept of deployment is dependent on the availability of a some
remote repository. Just as above, if that repository is not using
file:// (which is highly likely to be the case), or the repository is
not on a local filesystem, deployment will fail when offline.
** Testing mojos
This can be a problem if the tests are more than simple unit tests;
that is, if they require configuration of a server process, and
subsequent testing in-container.
Since we're only going to concern ourselves with states where localhost is
still active, we only need to worry about this case when the server container
is <<not>> installed on localhost. This allows the popular pattern of starting
a server container in-JVM, running tests against it, and shutting it down.
** SCM mojos
See below for discussion on SCM-related operations. Any mojo which
carries out some analysis or other interaction with a SCM system
will likely be unavailable when in offline mode.
* Implications for Subsystems
** Maven-Wagon
Parts of Wagon will continue to function normally. These include:
* The file wagon, provided the referenced location is on a local
filesystem.
It is not possible to determine whether a file-based location will
be available except on a case-by-case basis (or a root-url by
root-url basis). We may want to move the offline sensitivity entirely to
Maven-Artifact, below, so we can be smarter about testing filesystem-based
repositories, etc.
* If not otherwise specified, all other wagons are assumed to be
remote-only, and are therefore sensitive to offline mode.
** Maven-Artifact
This is wholly dependent on Maven-Wagon, above.
We could possibly use a flag on a particular Wagon to see whether it supports
offline mode, and then test to see if the file-based basedir for an aritfact
repository works...if it doesn't work, we can mark that repository offline...
OTOH, all offline-mode checks can probably be run from Wagon-based APIs.
** Maven-SCM
In all but trivial examples, SCM operations cannot complete without
having access to the versioning server. Therefore, it is assumed that
any SCM-related activity will be unavailable when m2 is in offline
mode.
** Maven-Core
We'll examine the different parts of maven-core on a case-by-case
basis, below:
*** DefaultLifecycleExecutor
When binding goals to the project's configured lifecycle, each mojo
descriptor should declare whether it requires online/offline status.
This value should be a java.lang.Boolean, so it can implement 3VL
(three value logic: yes, no, don't-care). The requiresOnline
field in the mojo descriptor has the following semantics:
[true] Online status is required for this mojo to function
correctly.
[false] <<(Default)>> Either status is acceptable for the mojo to
execute. It doesn't care.
The majority of mojos will leave the requiresOnline == false,
since online/offline status will be irrelevant, provided they have
access to their required artifacts and other classpath elements. In the case
of required artifacts and other classpath elemtents, this is assumed by the
mojo API to be in a correct state, and will be handled by the Wagon
modifications.
* Implementation Notes
** Accessibility of offline status
Offline status should be indicated in the MavenSettings instance, since it
can conceivably be set from either the settings.xml or the command-line.
In the event the '-o' switch is the impetus for setting offline mode, this
should result in modification of the active profile in the MavenSettings
instance, just as definition of the active profile from the command-line
should result in similar modification. This object is not meant to be
static within the build process, but rather to be setup as an aggregation of
all settings-related information passed into the system.
** Control over downloads
Find the control point for m2 using maven-wagon. At this point, inject
a offline status parameter which is used when retrieving the specific Wagon.
If <<<offline == true>>>:
* If the wagon is not bound to "file://", then ignore the request and print
a debug message.
* If the wagon is bound to "file://" then:
Retrieve the file or base-url file to be "downloaded".
* If the file (or more usefully, the base-url file) exists, proceed.
* If the file (or base-url file) doesn't exist, assume that this location
is part of a file-share. Ignore the request and print a debug message
as above.
** Control over mojos in the lifecycle
When binding a mojo to the project's lifecycle instance, check the mojo
descriptor's requiredConnectivity field.
* If <<<(offline == true) && (requiresOnline != true)>>>, bind
the mojo to the lifecycle.
In this case, the client is <<offline>>, and the mojo does not require
online status.
* If <<<(offline == false) && (requiresOnline == true)>>>, bind
the mojo to the lifecycle.
In this case, the client is <<online>>, and the mojo either requires
<<online>> status, or else doesn't care.
* Otherwise, don't bind the mojo. Log a debug message to indicate that it is
sensitive the the online state of the application, and that this state is
currently wrong for execution.
<<NOTE:>> Do we want to fail when we cannot bind a mojo to the lifecycle
because of offline/online status? That would probably indicate that the user
was trying to do something they cannot succeed at for now...so we probably
should throw an exception in this case.
|
