148 * @apiNote An output location may be used to write files in either
149 * a package-oriented organization or in a module-oriented organization.
150 *
151 * @return true if this is an output location, false otherwise
152 */
153 boolean isOutputLocation();
154
155 /**
156 * Indicates if this location is module-oriented location, and therefore
157 * expected to contain classes in a <em>module/package/class</em>
158 * hierarchy, as compared to a package-oriented location, which
159 * is expected to contain classes in a <em>package/class</em> hierarchy.
160 * The result of this method is undefined if this is an output
161 * location.
162 *
163 * @implNote This implementation returns true if the name includes
164 * the word "MODULE".
165 *
166 * @return true if this location is expected to contain modules
167 * @since 9
168 */
169 default boolean isModuleOrientedLocation() {
170 return getName().matches("\\bMODULE\\b");
171 }
172 }
173
174 /**
175 * Returns a class loader for loading plug-ins from the given
176 * package-oriented location.
177 * For example, to load annotation processors,
178 * a compiler will request a class loader for the {@link
179 * StandardLocation#ANNOTATION_PROCESSOR_PATH
180 * ANNOTATION_PROCESSOR_PATH} location.
181 *
182 * @param location a location
183 * @return a class loader for the given location; or {@code null}
184 * if loading plug-ins from the given location is disabled or if
185 * the location is not known
186 * @throws SecurityException if a class loader can not be created
187 * in the current security context
455 @Override
456 void close() throws IOException;
457
458 /**
459 * Gets a location for a named module within a location, which may be either
460 * a module-oriented location or an output location.
461 * The result will be an output location if the given location is
462 * an output location, or it will be a package-oriented location.
463 *
464 * @implSpec This implementation throws {@code UnsupportedOperationException}.
465 *
466 * @param location the module-oriented location
467 * @param moduleName the name of the module to be found
468 * @return the location for the named module
469 *
470 * @throws IOException if an I/O error occurred
471 * @throws UnsupportedOperationException if this operation if not supported by this file manager
472 * @throws IllegalArgumentException if the location is neither an output location nor a
473 * module-oriented location
474 * @since 9
475 */ // TODO: describe failure modes
476 default Location getLocationForModule(Location location, String moduleName) throws IOException {
477 throw new UnsupportedOperationException();
478 }
479
480 /**
481 * Gets a location for the module containing a specific file representing a Java
482 * source or class, to be found within a location, which may be either
483 * a module-oriented location or an output location.
484 * The result will be an output location if the given location is
485 * an output location, or it will be a package-oriented location.
486 *
487 * @apiNote the package name is used to identify the position of the file object
488 * within the <em>module/package/class</em> hierarchy identified by by the location.
489 *
490 * @implSpec This implementation throws {@code UnsupportedOperationException}.
491 *
492 * @param location the module-oriented location
493 * @param fo the file
494 * @param pkgName the package name for the class(es) defined in this file
495 * @return the module containing the file
496 *
497 * @throws IOException if an I/O error occurred
498 * @throws UnsupportedOperationException if this operation if not supported by this file manager
499 * @throws IllegalArgumentException if the location is neither an output location nor a
500 * module-oriented location
501 * @since 9
502 */
503 default Location getLocationForModule(Location location, JavaFileObject fo, String pkgName) throws IOException {
504 throw new UnsupportedOperationException();
505 }
506
507 /**
508 * Get a service loader for a specific service class from a given location.
509 *
510 * If the location is a module-oriented location, the service loader will use the
511 * service declarations in the modules found in that location. Otherwise, a service loader
512 * is created using the package-oriented location, in which case, the services are
513 * determined using the provider-configuration files in {@code META-INF/services}.
514 *
515 * @implSpec This implementation throws {@code UnsupportedOperationException}.
516 *
517 * @param location the module-oriented location
518 * @param service the {@code Class} object of the service class
519 * @param <S> the service class
520 * @return a service loader for the given service class
521 *
522 * @throws IOException if an I/O error occurred
523 * @throws UnsupportedOperationException if this operation if not supported by this file manager
524 * @since 9
525 */ // TODO: describe failure modes
526 default <S> ServiceLoader<S> getServiceLoader(Location location, Class<S> service) throws IOException {
527 throw new UnsupportedOperationException();
528 }
529
530 /**
531 * Infer the name of the module from its location, as returned by
532 * {@code getLocationForModule} or {@code listModuleLocations}.
533 *
534 * @implSpec This implementation throws {@code UnsupportedOperationException}.
535 *
536 * @param location a package-oriented location representing a module
537 * @return the name of the module
538 *
539 * @throws IOException if an I/O error occurred
540 * @throws UnsupportedOperationException if this operation if not supported by this file manager
541 * @throws IllegalArgumentException if the location is not one known to this file manager
542 * @since 9
543 */ // TODO: describe failure modes
544 default String inferModuleName(Location location) throws IOException {
545 throw new UnsupportedOperationException();
546 }
547
548 /**
549 * Lists the locations for all the modules in a module-oriented location or an output location.
550 * The locations that are returned will be output locations if the given location is an output,
551 * or it will be a package-oriented locations.
552 *
553 * @implSpec This implementation throws {@code UnsupportedOperationException}.
554 *
555 * @param location the module-oriented location for which to list the modules
556 * @return a series of sets of locations containing modules
557 *
558 * @throws IOException if an I/O error occurred
559 * @throws UnsupportedOperationException if this operation if not supported by this file manager
560 * @throws IllegalArgumentException if the location is not a module-oriented location
561 * @since 9
562 */ // TODO: describe failure modes
563 default Iterable<Set<Location>> listLocationsForModules(Location location) throws IOException {
564 throw new UnsupportedOperationException();
565 }
566
567 }
|
148 * @apiNote An output location may be used to write files in either
149 * a package-oriented organization or in a module-oriented organization.
150 *
151 * @return true if this is an output location, false otherwise
152 */
153 boolean isOutputLocation();
154
155 /**
156 * Indicates if this location is module-oriented location, and therefore
157 * expected to contain classes in a <em>module/package/class</em>
158 * hierarchy, as compared to a package-oriented location, which
159 * is expected to contain classes in a <em>package/class</em> hierarchy.
160 * The result of this method is undefined if this is an output
161 * location.
162 *
163 * @implNote This implementation returns true if the name includes
164 * the word "MODULE".
165 *
166 * @return true if this location is expected to contain modules
167 * @since 9
168 * @spec JPMS
169 */
170 default boolean isModuleOrientedLocation() {
171 return getName().matches("\\bMODULE\\b");
172 }
173 }
174
175 /**
176 * Returns a class loader for loading plug-ins from the given
177 * package-oriented location.
178 * For example, to load annotation processors,
179 * a compiler will request a class loader for the {@link
180 * StandardLocation#ANNOTATION_PROCESSOR_PATH
181 * ANNOTATION_PROCESSOR_PATH} location.
182 *
183 * @param location a location
184 * @return a class loader for the given location; or {@code null}
185 * if loading plug-ins from the given location is disabled or if
186 * the location is not known
187 * @throws SecurityException if a class loader can not be created
188 * in the current security context
456 @Override
457 void close() throws IOException;
458
459 /**
460 * Gets a location for a named module within a location, which may be either
461 * a module-oriented location or an output location.
462 * The result will be an output location if the given location is
463 * an output location, or it will be a package-oriented location.
464 *
465 * @implSpec This implementation throws {@code UnsupportedOperationException}.
466 *
467 * @param location the module-oriented location
468 * @param moduleName the name of the module to be found
469 * @return the location for the named module
470 *
471 * @throws IOException if an I/O error occurred
472 * @throws UnsupportedOperationException if this operation if not supported by this file manager
473 * @throws IllegalArgumentException if the location is neither an output location nor a
474 * module-oriented location
475 * @since 9
476 * @spec JPMS
477 */ // TODO: describe failure modes
478 default Location getLocationForModule(Location location, String moduleName) throws IOException {
479 throw new UnsupportedOperationException();
480 }
481
482 /**
483 * Gets a location for the module containing a specific file representing a Java
484 * source or class, to be found within a location, which may be either
485 * a module-oriented location or an output location.
486 * The result will be an output location if the given location is
487 * an output location, or it will be a package-oriented location.
488 *
489 * @apiNote the package name is used to identify the position of the file object
490 * within the <em>module/package/class</em> hierarchy identified by by the location.
491 *
492 * @implSpec This implementation throws {@code UnsupportedOperationException}.
493 *
494 * @param location the module-oriented location
495 * @param fo the file
496 * @param pkgName the package name for the class(es) defined in this file
497 * @return the module containing the file
498 *
499 * @throws IOException if an I/O error occurred
500 * @throws UnsupportedOperationException if this operation if not supported by this file manager
501 * @throws IllegalArgumentException if the location is neither an output location nor a
502 * module-oriented location
503 * @since 9
504 * @spec JPMS
505 */
506 default Location getLocationForModule(Location location, JavaFileObject fo, String pkgName) throws IOException {
507 throw new UnsupportedOperationException();
508 }
509
510 /**
511 * Get a service loader for a specific service class from a given location.
512 *
513 * If the location is a module-oriented location, the service loader will use the
514 * service declarations in the modules found in that location. Otherwise, a service loader
515 * is created using the package-oriented location, in which case, the services are
516 * determined using the provider-configuration files in {@code META-INF/services}.
517 *
518 * @implSpec This implementation throws {@code UnsupportedOperationException}.
519 *
520 * @param location the module-oriented location
521 * @param service the {@code Class} object of the service class
522 * @param <S> the service class
523 * @return a service loader for the given service class
524 *
525 * @throws IOException if an I/O error occurred
526 * @throws UnsupportedOperationException if this operation if not supported by this file manager
527 * @since 9
528 * @spec JPMS
529 */ // TODO: describe failure modes
530 default <S> ServiceLoader<S> getServiceLoader(Location location, Class<S> service) throws IOException {
531 throw new UnsupportedOperationException();
532 }
533
534 /**
535 * Infer the name of the module from its location, as returned by
536 * {@code getLocationForModule} or {@code listModuleLocations}.
537 *
538 * @implSpec This implementation throws {@code UnsupportedOperationException}.
539 *
540 * @param location a package-oriented location representing a module
541 * @return the name of the module
542 *
543 * @throws IOException if an I/O error occurred
544 * @throws UnsupportedOperationException if this operation if not supported by this file manager
545 * @throws IllegalArgumentException if the location is not one known to this file manager
546 * @since 9
547 * @spec JPMS
548 */ // TODO: describe failure modes
549 default String inferModuleName(Location location) throws IOException {
550 throw new UnsupportedOperationException();
551 }
552
553 /**
554 * Lists the locations for all the modules in a module-oriented location or an output location.
555 * The locations that are returned will be output locations if the given location is an output,
556 * or it will be a package-oriented locations.
557 *
558 * @implSpec This implementation throws {@code UnsupportedOperationException}.
559 *
560 * @param location the module-oriented location for which to list the modules
561 * @return a series of sets of locations containing modules
562 *
563 * @throws IOException if an I/O error occurred
564 * @throws UnsupportedOperationException if this operation if not supported by this file manager
565 * @throws IllegalArgumentException if the location is not a module-oriented location
566 * @since 9
567 * @spec JPMS
568 */ // TODO: describe failure modes
569 default Iterable<Set<Location>> listLocationsForModules(Location location) throws IOException {
570 throw new UnsupportedOperationException();
571 }
572
573 }
|