Skip to content

Commit 852c52d

Browse files
joakimejoakime
authored
Cleanup javadoc for recently deprecated Context newResource methods. (#15354)
1 parent ce0c7f5 commit 852c52d

6 files changed

Lines changed: 228 additions & 42 deletions

File tree

‎jetty-core/jetty-util/src/main/java/org/eclipse/jetty/util/resource/ResourceFactory.java‎

Lines changed: 211 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -160,7 +160,17 @@ static Resource combine(Resource... resources)
160160
}
161161

162162
/**
163-
* Construct a resource from a uri.
163+
* Construct a resource from a URI.
164+
*
165+
* <p>
166+
* Each call may allocate a new JVM resource, whose lifecycle
167+
* is tied to this ResourceFactory implementation.
168+
* </p>
169+
*
170+
* <p>
171+
* This method is used to create root (or base) resources.
172+
* Child resources of these resources, should be created using {@link Resource#resolve(String)}
173+
* </p>
164174
*
165175
* @param uri A URI.
166176
* @return A Resource object.
@@ -170,6 +180,16 @@ static Resource combine(Resource... resources)
170180
/**
171181
* <p>Construct a Resource from a string reference into classloaders.</p>
172182
*
183+
* <p>
184+
* Each call may allocate a new JVM resource, whose lifecycle
185+
* is tied to this ResourceFactory implementation.
186+
* </p>
187+
*
188+
* <p>
189+
* This method is used to create root (or base) resources.
190+
* Child resources of these resources, should be created using {@link Resource#resolve(String)}
191+
* </p>
192+
*
173193
* @param resource Resource as string representation
174194
* @return The new Resource
175195
* @throws IllegalArgumentException if string is blank
@@ -203,6 +223,16 @@ default Resource newSystemResource(String resource)
203223
* then the non-slash version is also tried against the same ClassLoader (example: {@code org/example/ClassName.class}).
204224
* </p>
205225
*
226+
* <p>
227+
* Each call may allocate a new JVM resource, whose lifecycle
228+
* is tied to this ResourceFactory implementation.
229+
* </p>
230+
*
231+
* <p>
232+
* This method is used to create root (or base) resources.
233+
* Child resources of these resources, should be created using {@link Resource#resolve(String)}
234+
* </p>
235+
*
206236
* @param resource the resource name to find in a classloader
207237
* @param searchSystemClassLoader true to search {@link ClassLoader#getSystemResource(String)}, false to skip
208238
* @return The new Resource, which may be a {@link CombinedResource} if multiple directory resources are found.
@@ -276,6 +306,16 @@ interface Source
276306
* Convenience method for {@code newClassLoaderResource(resource, true)}
277307
* </p>
278308
*
309+
* <p>
310+
* Each call may allocate a new JVM resource, whose lifecycle
311+
* is tied to this ResourceFactory implementation.
312+
* </p>
313+
*
314+
* <p>
315+
* This method is used to create root (or base) resources.
316+
* Child resources of these resources, should be created using {@link Resource#resolve(String)}
317+
* </p>
318+
*
279319
* @param resource string representation of resource to find in a classloader
280320
* @return The new Resource
281321
* @throws IllegalArgumentException if string is blank
@@ -293,6 +333,16 @@ default Resource newClassLoaderResource(String resource)
293333
* Convenience method {@code .newClassLoaderResource(resource, false)}
294334
* </p>
295335
*
336+
* <p>
337+
* Each call may allocate a new JVM resource, whose lifecycle
338+
* is tied to this ResourceFactory implementation.
339+
* </p>
340+
*
341+
* <p>
342+
* This method is used to create root (or base) resources.
343+
* Child resources of these resources, should be created using {@link Resource#resolve(String)}
344+
* </p>
345+
*
296346
* @param resource the relative name of the resource
297347
* @return Resource
298348
* @throws IllegalArgumentException if string is blank
@@ -311,10 +361,14 @@ default Resource newClassPathResource(String resource)
311361
* </p>
312362
*
313363
* <p>
314-
* A Memory Resource is created from a the contents of
315-
* {@link URL#openStream()} and kept in memory from
316-
* that point forward. Never accessing the URL
317-
* again to refresh it's contents.
364+
* Each call will create a new Memory Resource from the contents of
365+
* {@link URL#openStream()} and kept in memory for the duration
366+
* of this ResourceFactory implementation. Never accessing the URL
367+
* again to refresh its contents.
368+
* </p>
369+
*
370+
* <p>
371+
* The created Memory Resource does not support child resources.
318372
* </p>
319373
*
320374
* @param url the URL to load into memory
@@ -333,6 +387,16 @@ default Resource newMemoryResource(URL url)
333387
/**
334388
* Construct a resource from a string.
335389
*
390+
* <p>
391+
* Each call may allocate a new JVM resource, whose lifecycle
392+
* is tied to this ResourceFactory implementation.
393+
* </p>
394+
*
395+
* <p>
396+
* This method is used to create root (or base) resources.
397+
* Child resources of these resources, should be created using {@link Resource#resolve(String)}
398+
* </p>
399+
*
336400
* @param resource A URL or filename.
337401
* @return A Resource object, or null if the string points to a location
338402
* that does not exist
@@ -388,6 +452,16 @@ default Resource newResource(String resource)
388452
/**
389453
* Construct a Resource from provided path.
390454
*
455+
* <p>
456+
* Each call may allocate a new JVM resource, whose lifecycle
457+
* is tied to this ResourceFactory implementation.
458+
* </p>
459+
*
460+
* <p>
461+
* This method is used to create root (or base) resources.
462+
* Child resources of these resources, should be created using {@link Resource#resolve(String)}
463+
* </p>
464+
*
391465
* @param path the path
392466
* @return the Resource for the provided path, or null if the path
393467
* does not exist
@@ -404,6 +478,16 @@ default Resource newResource(Path path)
404478
/**
405479
* Construct a possible combined {@code Resource} from a list of URIs.
406480
*
481+
* <p>
482+
* Each call may allocate a new JVM resource, whose lifecycle
483+
* is tied to this ResourceFactory implementation.
484+
* </p>
485+
*
486+
* <p>
487+
* This method is used to create root (or base) resources.
488+
* Child resources of these resources, should be created using {@link Resource#resolve(String)}
489+
* </p>
490+
*
407491
* @param uris the URIs
408492
* @return the Resource for the provided URIs, or null if all
409493
* the provided URIs do not exist
@@ -420,6 +504,16 @@ default Resource newResource(List<URI> uris)
420504
/**
421505
* Construct a {@link Resource} from a provided URL.
422506
*
507+
* <p>
508+
* Each call may allocate a new JVM resource, whose lifecycle
509+
* is tied to this ResourceFactory implementation.
510+
* </p>
511+
*
512+
* <p>
513+
* This method is used to create root (or base) resources.
514+
* Child resources of these resources, should be created using {@link Resource#resolve(String)}
515+
* </p>
516+
*
423517
* @param url the URL
424518
* @return the Resource for the provided URL, or null if the
425519
* url points to a location that does not exist
@@ -443,6 +537,16 @@ default Resource newResource(URL url)
443537
/**
444538
* Construct a {@link Resource} from a {@code file:} based URI that is mountable (eg: a jar file).
445539
*
540+
* <p>
541+
* Each call will allocate a new JVM resource, whose lifecycle
542+
* is tied to this ResourceFactory implementation.
543+
* </p>
544+
*
545+
* <p>
546+
* This method is used to create root (or base) resources.
547+
* Child resources of these resources, should be created using {@link Resource#resolve(String)}
548+
* </p>
549+
*
446550
* @param uri the URI
447551
* @return the Resource, mounted as a {@link java.nio.file.FileSystem}, or null if
448552
* the uri points to a location that does not exist.
@@ -462,6 +566,16 @@ default Resource newJarFileResource(URI uri)
462566
* The supported types: {@link Path}, {@link String}, {@link URI}, {@link URL}, and {@link Resource}
463567
* </p>
464568
*
569+
* <p>
570+
* Each call may allocate a new JVM resource, whose lifecycle
571+
* is tied to this ResourceFactory implementation.
572+
* </p>
573+
*
574+
* <p>
575+
* This method is used to create root (or base) resources.
576+
* Child resources of these resources, should be created using {@link Resource#resolve(String)}
577+
* </p>
578+
*
465579
* @param obj if the object to convert
466580
* @return the Resource representing the provided obj
467581
* @throws IllegalArgumentException if the object is none of the supported types.
@@ -487,13 +601,30 @@ default Resource asResource(Object obj)
487601

488602
/**
489603
* Split a string of references, that may be split with '{@code ,}', or '{@code ;}', or '{@code |}' into a List of {@link Resource}.
604+
*
490605
* <p>
491-
* Each part of the input string could be path references (unix or windows style), string URI references, or even glob references (eg: {@code /path/to/libs/*}).
606+
* Each part of the input string could be path references (UNIX or windows style), string URI references, or even glob references (eg: {@code /path/to/libs/*}).
492607
* </p>
608+
*
609+
* <p>
610+
* Convenience method for {@code split(string, ",;|", false)}
611+
* </p>
612+
*
493613
* <p>
494614
* If the result of processing the input segment is a java archive, it will not automatically be mounted, the caller must perform the mount if necessary
495615
* </p>
496616
*
617+
* <p>
618+
* Each call may allocate a new JVM resource, whose lifecycle
619+
* is tied to this ResourceFactory implementation.
620+
* </p>
621+
*
622+
* <p>
623+
* This method is used to create a List of root (or base) resources.
624+
* Consider using {@link #combine(Resource...)} to make them into a single {@link Resource}.
625+
* Child resources of these resources, should be created using {@link Resource#resolve(String)}
626+
* </p>
627+
*
497628
* @param str the input string of references
498629
* @return list of resources
499630
*/
@@ -502,31 +633,104 @@ default List<Resource> split(String str)
502633
return split(str, ",;|", false);
503634
}
504635

636+
/**
637+
* Split a string of references, that may be split with '{@code ,}', or '{@code ;}', or '{@code |}' into a List of {@link Resource}.
638+
*
639+
* <p>
640+
* Each part of the input string could be path references (UNIX or windows style), string URI references, or even glob references (eg: {@code /path/to/libs/*}).
641+
* </p>
642+
*
643+
* <p>
644+
* Convenience method for {@code split(string, ",;|", unwrap)}
645+
* </p>
646+
*
647+
* <p>
648+
* If the result of processing the input segment is a java archive, it will not automatically be mounted, the caller must perform the mount if necessary
649+
* </p>
650+
*
651+
* <p>
652+
* Each call may allocate a new JVM resource, whose lifecycle
653+
* is tied to this ResourceFactory implementation.
654+
* </p>
655+
*
656+
* <p>
657+
* This method is used to create a List of root (or base) resources.
658+
* Consider using {@link #combine(Resource...)} to make them into a single {@link Resource}.
659+
* Child resources of these resources, should be created using {@link Resource#resolve(String)}
660+
* </p>
661+
*
662+
* @param str the input string of references
663+
* @param unwrap if true {@code jar:file} references will be unwrapped back to just the container
664+
* @return list of resources
665+
*/
505666
default List<Resource> split(String str, boolean unwrap)
506667
{
507668
return split(str, ",;|", unwrap);
508669
}
509670

671+
/**
672+
* Split a string of references, that may be split with '{@code ,}', or '{@code ;}', or '{@code |}' into a List of {@link Resource}.
673+
*
674+
* <p>
675+
* Each part of the input string could be path references (UNIX or windows style), string URI references, or even glob references (eg: {@code /path/to/libs/*}).
676+
* </p>
677+
*
678+
* <p>
679+
* Convenience method for {@code split(string, delim, false)}
680+
* </p>
681+
*
682+
* <p>
683+
* If the result of processing the input segment is a java archive, it will not automatically be mounted, the caller must perform the mount if necessary
684+
* </p>
685+
*
686+
* <p>
687+
* Each call may allocate a new JVM resource, whose lifecycle
688+
* is tied to this ResourceFactory implementation.
689+
* </p>
690+
*
691+
* <p>
692+
* This method is used to create a List of root (or base) resources.
693+
* Consider using {@link #combine(Resource...)} to make them into a single {@link Resource}.
694+
* Child resources of these resources, should be created using {@link Resource#resolve(String)}
695+
* </p>
696+
*
697+
* @param str the input string of references
698+
* @param delim if true {@code jar:file} references will be unwrapped back to just the container
699+
* @return list of resources
700+
*/
510701
default List<Resource> split(String str, String delim)
511702
{
512703
return split(str, delim, false);
513704
}
514705

515706
/**
516707
* Split a string of references by provided delims into a List of {@link Resource}.
708+
*
517709
* <p>
518710
* Each part of the input string could be path references (unix or windows style),
519711
* string URI references, or even glob references (eg: {@code /path/to/libs/*}).
520712
* Note: that if you use the {@code :} character in your delims, then URI references will be impossible.
521713
* </p>
714+
*
522715
* <p>
523716
* If the result of processing the input segment is a java archive it will not be automatically mounted,
524717
* the caller must mount if necessary
525718
* </p>
526719
*
720+
* <p>
721+
* Each call may allocate a new JVM resource, whose lifecycle
722+
* is tied to this ResourceFactory implementation.
723+
* </p>
724+
*
725+
* <p>
726+
* This method is used to create a List of root (or base) resources.
727+
* Consider using {@link #combine(Resource...)} to make them into a single {@link Resource}.
728+
* Child resources of these resources, should be created using {@link Resource#resolve(String)}
729+
* </p>
730+
*
527731
* @param str the input string of references
528732
* @param delims the list of delimiters
529-
* @param unwrap if true jar:file references will be unwrapped back to just the container
733+
* @param unwrap if true {@code jar:file} references will be unwrapped back to just the container
530734
* @return list of resources
531735
*/
532736
default List<Resource> split(String str, String delims, boolean unwrap)

‎jetty-ee10/jetty-ee10-servlet/src/main/java/org/eclipse/jetty/ee10/servlet/ResourceServlet.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@
7979
* <dd>
8080
* The root directory to look for static resources. Defaults to the context's baseResource. Relative URI
8181
* are {@link Resource#resolve(String) resolved} against the context's {@link ServletContextHandler#getBaseResource()}
82-
* base resource, all other values are resolved using {@link ServletContextHandler#newResource(String)}.
82+
* base resource.
8383
* </dd>
8484
* <dt>cacheControl</dt>
8585
* <dd>

‎jetty-ee10/jetty-ee10-servlet/src/main/java/org/eclipse/jetty/ee10/servlet/ServletContextHandler.java‎

Lines changed: 5 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -798,9 +798,7 @@ public Resource getResource(String pathInContext) throws MalformedURLException
798798
* @param url the url to convert to a Resource
799799
* @return the Resource for that url
800800
* @throws IOException if unable to create a Resource from the URL
801-
* @deprecated use {@code ResourceFactory.of(component).newResource(URL)} properly
802-
* at webapp initialization time only. The use of this method during
803-
* context started phase can result in excessive memory consumption.
801+
* @deprecated do not use this method, use {@link ResourceFactory#newResource(URL)}.
804802
*/
805803
@Deprecated(since = "12.1.11", forRemoval = true)
806804
public Resource newResource(URL url) throws IOException
@@ -809,13 +807,11 @@ public Resource newResource(URL url) throws IOException
809807
}
810808

811809
/**
812-
* Convert URL to Resource wrapper for {@link ResourceFactory#newResource(URL)} enables extensions to provide alternate resource implementations.
810+
* Convert URI to Resource wrapper for {@link ResourceFactory#newResource(URI)} enables extensions to provide alternate resource implementations.
813811
*
814812
* @param uri the URI to convert to a Resource
815813
* @return the Resource for that URI
816-
* @deprecated use {@code ResourceFactory.of(component).newResource(URI)} properly
817-
* at webapp initialization time only. The use of this method during
818-
* context started phase can result in excessive memory consumption.
814+
* @deprecated do not use this method, use {@link ResourceFactory#newResource(URI)}.
819815
*/
820816
@Deprecated(since = "12.1.11", forRemoval = true)
821817
public Resource newResource(URI uri)
@@ -824,13 +820,11 @@ public Resource newResource(URI uri)
824820
}
825821

826822
/**
827-
* Convert a URL or path to a Resource. The default implementation is a wrapper for {@link ResourceFactory#newResource(String)}.
823+
* Convert a String URL or Path to a Resource. The default implementation is a wrapper for {@link ResourceFactory#newResource(String)}.
828824
*
829825
* @param urlOrPath The URL or path to convert
830826
* @return The Resource for the URL/path
831-
* @deprecated use {@code ResourceFactory.of(component).newResource(String)} properly
832-
* at webapp initialization time only. The use of this method during
833-
* context started phase can result in excessive memory consumption.
827+
* @deprecated do not use this method, use {@link ResourceFactory#newResource(String)}.
834828
*/
835829
@Deprecated(since = "12.1.11", forRemoval = true)
836830
public Resource newResource(String urlOrPath)

0 commit comments

Comments
 (0)