Класс ClassLoader

public abstract class ClassLoader
extends Object

Класс загрузчик классов — это объект, ответственный за загрузку классов. Класс ClassLoader — абстрактный класс. Учитывая бинарное имя класса, загрузчик классов должен попытаться найти или сгенерировать данные, составляющие определение класса. Типичная стратегия заключается в преобразовании имени в имя файла и затем чтении «файла класса» с таким именем из файловой системы.

Каждый объект Class содержит ссылку на reference на загрузчик, который его определил.

Объекты для классов массивов не создаются загрузчиками классов, а создаются автоматически по мере необходимости Java-средой выполнения. Загрузчик класса массива, возвращаемый методом Class.getClassLoader(), такой же, как и загрузчик класса его элемента; если тип элемента — примитивный тип, то массив класса не имеет загрузчика.

Приложения реализуют подклассы ClassLoader для расширения способа динамической загрузки классов Java-виртуальной машиной.

Загрузчики классов могут использоваться менеджерами безопасности для указания областей безопасности.

Класс ClassLoader использует модель делегирования для поиска классов и ресурсов. Каждый экземпляр ClassLoader имеет связанный родительский загрузчик классов. При запросе поиска класса или ресурса экземпляр ClassLoader делегирует поиск родительскому загрузчику классов, прежде чем попытаться найти класс или ресурс самостоятельно. Встроенный загрузчик классов виртуальной машины, называемый «bootstrap class loader», сам по себе не имеет родителя, но может служить родителем экземпляра ClassLoader.

Загрузчики классов, поддерживающие одновременную загрузку классов, известны как параллельно-способные загрузчики классов и обязаны зарегистрировать себя во время инициализации класса, вызвав метод ClassLoader.registerAsParallelCapable. Обратите внимание, что класс ClassLoader по умолчанию зарегистрирован как параллельно-способный. Однако его подклассы по-прежнему должны зарегистрировать себя, если они параллельно-способные.
В средах, в которых модель делегирования не является строго иерархической, загрузчики классов должны быть параллельно-способными, в противном случае загрузка классов может привести к тупиковым ситуациям, потому что блокировка загрузчика удерживается на все время процесса загрузки класса (см. методы loadClass).

Обычно Java-виртуальная машина загружает классы из локальной файловой системы зависимым от платформы способом. Например, в системах UNIX виртуальная машина загружает классы из каталога, определённого переменной среды CLASSPATH.

Однако некоторые классы могут не происходить из файла; они могут происходить из других источников, таких как сеть, или они могут быть созданы приложением. Метод defineClass преобразует массив байтов в экземпляр класса Class. Экземпляры этого вновь определённого класса можно создать с помощью Class.newInstance.

Методы и конструкторы объектов, созданных загрузчиком классов, могут ссылаться на другие классы. Для определения ссылаемых классов Java-виртуальная машина вызывает метод loadClass загрузчика классов, который первоначально создал класс.

Например, приложение может создать сетевой загрузчик классов для загрузки файлов классов с сервера. Пример кода может выглядеть следующим образом:

ClassLoader loader = new NetworkClassLoader(host, port);
Object main = loader.loadClass("Main", true).newInstance();
     . . .

Подкласс сетевого загрузчика классов должен определить методы findClass и loadClassData для загрузки класса из сети. После загрузки байтов, составляющих класс, он должен использовать метод defineClass для создания экземпляра класса. Пример реализации:

class NetworkClassLoader extends ClassLoader {
    String host;
    int port;

    public Class findClass(String name) {
        byte[] b = loadClassData(name);
        return defineClass(name, b, 0, b.length);
    }

    private byte[] loadClassData(String name) {
        // load the class data from the connection
         . . .
    }
}

Бинарные имена

Любое имя класса, предоставленное в качестве параметра String методам в ClassLoader, должно быть бинарным именем, как определено в Спецификации языка Java™.

Примеры допустимых имён классов включают:

"java.lang.String"
"javax.swing.JSpinner$DefaultEditor"
"java.security.KeyStore$Builder$FileBuilder$1"
"java.net.URLClassLoader$3$1"

Конструкторы

ClassLoader

protected ClassLoader(ClassLoader parent)

Параметры:

parent - Родительский загрузчик классов

Исключения:

SecurityException - Если менеджер безопасности существует и его метод checkCreateClassLoader не разрешает создание нового загрузчика классов.

С:

1.2

ClassLoader

protected ClassLoader()

Исключения:

SecurityException - Если менеджер безопасности существует и его метод checkCreateClassLoader не разрешает создание нового загрузчика классов.

Методы

loadClass

public Class<?> loadClass(String name)
                   throws ClassNotFoundException

Загружает класс с указанным бинарным именем. Этот метод ищет классы аналогичным образом, как и метод loadClass(String, boolean). Он вызывается виртуальной машиной Java для разрешения ссылок на классы. Вызов этого метода эквивалентен вызову loadClass(name, false).

Параметры:

name - Бинарное имя класса

Возвращает:

Возвращаемый объект Class

Исключения:

ClassNotFoundException - Если класс не был найден

loadClass

protected Class<?> loadClass(String name,
                             boolean resolve)
                      throws ClassNotFoundException

Параметры:

name - Бинарное имя класса

resolve - Если true , то разрешить класс

Возвращает:

Возвращаемый объект Class

Исключения:

ClassNotFoundException - Если класс не был найден

getClassLoadingLock

protected Object getClassLoadingLock(String className)

Возвращает объект блокировки для операций загрузки классов. Для обратной совместимости, базовая реализация этого метода выполняет следующее. Если этот объект ClassLoader зарегистрирован как способный к параллельной работе, метод возвращает выделенный объект, связанный с указанным именем класса. В противном случае метод возвращает этот объект ClassLoader.

Параметры:

className - Имя класса, который требуется загрузить

Возвращает:

блокировка для операций загрузки классов

Исключения:

NullPointerException - Если зарегистрирован как способный к параллельной работе и className равен null

С:

1.7

См. также:

loadClass(String, boolean)

findClass

protected Class<?> findClass(String name)
                      throws ClassNotFoundException

Ищет класс с указанным бинарным именем. Этот метод должен быть переопределён реализациями загрузчика классов, которые следуют модели делегирования для загрузки классов, и будет вызван методом loadClass после проверки родительского загрузчика классов на наличие запрашиваемого класса. Базовая реализация выбрасывает ClassNotFoundException.

Параметры:

name - Бинарное имя класса

Возвращает:

Возвращаемый объект Class

Исключения:

ClassNotFoundException - Если класс не был найден

С:

1.2

defineClass

@Deprecated
protected final Class<?> defineClass(byte[] b,
                                                 int off,
                                                 int len)
                                          throws ClassFormatError

Устарело. Заменено на defineClass(String, byte[], int, int)

Преобразует массив байтов в экземпляр класса Class. Перед использованием Class он должен быть разрешен. Этот метод устарел в пользу версии, которая принимает бинарное имя в качестве первого аргумента и более безопасен.

Параметры:

b - Байты, составляющие данные класса. Байты в позициях off по off+len-1 должны иметь формат действительного файла класса, как определено в Спецификации виртуальной машины Java™.

off - Начальный смещение в b данных класса

len - Длина данных класса

Возвращает:

Объект Class, созданный из указанных данных класса

Исключения:

ClassFormatError - Если данные не содержали действительного класса

IndexOutOfBoundsException - Если либо off или len отрицательны, или если off+len больше b.length.

SecurityException - Если попытка добавить этот класс в пакет, содержащий классы, подписанные другой набором сертификатов, чем этот класс, или если попытка определить класс в пакете с полным именем, начинающимся с "java.".

См. также:

loadClass(String, boolean), resolveClass(Class)

defineClass

protected final Class<?> defineClass(String name,
                                     byte[] b,
                                     int off,
                                     int len)
                              throws ClassFormatError

Параметры:

name - Ожидаемое бинарное имя класса, или null если оно неизвестно

b - Байты, составляющие данные класса. Байты в позициях off по off+len-1 должны иметь формат действительного файла класса, как определено в Спецификации виртуальной машины Java™.

off - Начальное смещение в b данных класса

len - Длина данных класса

Возвращает:

Объект Class, созданный из указанных данных класса.

Исключения:

ClassFormatError - Если данные не содержали действительного класса

IndexOutOfBoundsException - Если либо off или len отрицательны, или если off+len больше b.length.

SecurityException - Если попытка добавить этот класс в пакет, содержащий классы, подписанные другим набором сертификатов, чем этот класс (который не подписан), или если name начинается с "java.".

С:

1.1

См. также:

loadClass(String, boolean), resolveClass(Class), CodeSource, SecureClassLoader

defineClass

protected final Class<?> defineClass(String name,
                                     byte[] b,
                                     int off,
                                     int len,
                                     ProtectionDomain protectionDomain)
                              throws ClassFormatError

Параметры:

name - Ожидаемое бинарное имя класса или null, если оно неизвестно

b - Байты, составляющие данные класса. Байты с позиций off по off+len-1 должны иметь формат допустимого файла класса, определённого в Спецификации виртуальной машины Java™.

off - Начальный смещение в b данных класса

len - Длина данных класса

protectionDomain - ProtectionDomain класса

Возвращает:

Объект Class, созданный из данных, и необязательный ProtectionDomain.

Исключения:

ClassFormatError - Если данные не содержали допустимого класса

NoClassDefFoundError - Если name не равно бинарному имени класса, заданному b

IndexOutOfBoundsException - Если off или len отрицательные, или если off+len больше b.length.

SecurityException - Если попытка добавить этот класс в пакет, содержащий классы, подписанные другим набором сертификатов, чем этот класс, или если name начинается с "java.".

defineClass

protected final Class<?> defineClass(String name,
                                     ByteBuffer b,
                                     ProtectionDomain protectionDomain)
                              throws ClassFormatError

Параметры:

name - Ожидаемое бинарное имя класса, или null , если оно неизвестно

b - Байты, составляющие данные класса. Байты с позиций b.position() по b.position() + b.limit() -1 должны иметь формат допустимого файла класса, определённого в Спецификации виртуальной машины Java™.

protectionDomain - ProtectionDomain класса или null.

Возвращает:

Объект Class, созданный из данных, и необязательный ProtectionDomain.

Исключения:

ClassFormatError - Если данные не содержали допустимого класса.

NoClassDefFoundError - Если name не равно бинарному имени класса, заданному b

SecurityException - Если попытка добавить этот класс в пакет, содержащий классы, подписанные другим набором сертификатов, чем этот класс, или если name начинается с "java.".

С:

1.5

См. также:

defineClass(String, byte[], int, int, ProtectionDomain)

resolveClass

protected final void resolveClass(Class<?> c)

Связывает указанный класс. Этот (вводящий в заблуждение) метод может использоваться загрузчиком классов для связи класса. Если класс c уже связан, то этот метод просто возвращает значение. В противном случае класс связывается, как описано в главе "Исполнение" Спецификации языка Java™.

Параметры:

c - Класс для связи

Исключения:

NullPointerException - Если c равно null.

См. также:

defineClass(String, byte[], int, int)

findSystemClass

protected final Class<?> findSystemClass(String name)
                                  throws ClassNotFoundException

Параметры:

name - Бинарное имя класса

Возвращает:

Объект Class для указанного name

Исключения:

ClassNotFoundException - Если класс не был найден

См. также:

ClassLoader(ClassLoader), getParent()

findLoadedClass

protected final Class<?> findLoadedClass(String name)

Возвращает класс с данным бинарным именем, если этот загрузчик был зарегистрирован виртуальной машиной Java как инициатор загрузки класса с этим бинарным именем. В противном случае возвращается null.

Параметры:

name - Бинарное имя класса

Возвращает:

Объект Class или null , если класс не был загружен

С:

1.1

setSigners

protected final void setSigners(Class<?> c,
                                Object[] signers)

Устанавливает подписывающие классы. Это следует вызывать после определения класса.

Параметры:

c - Объект Class

signers - Подписывающие классы

С:

1.1

getResource

public URL getResource(String name)

Примечание API:

При переопределении этого метода рекомендуется, чтобы реализация гарантировала, что любая делегация согласуется с методом getResources(String).

Параметры:

name - Имя ресурса

Возвращает:

Объект URL для чтения ресурса или null , если ресурс не был найден или у вызывающего нет достаточных привилегий для получения ресурса.

С:

1.1

getResources

public Enumeration<URL> getResources(String name)
                              throws IOException

Примечание API:

При переопределении этого метода рекомендуется, чтобы реализация гарантировала, что любая делегация согласуется с методом getResource(String). Это должно гарантировать, что первый элемент, возвращаемый методом nextElement перечисления, является тем же ресурсом, что и тот, который вернул бы метод getResource(String).

Параметры:

name - Имя ресурса

Возвращает:

Перечисление объектов URL для ресурса. Если ресурсы не были найдены, перечисление будет пустым. Ресурсы, к которым загрузчик классов не имеет доступа, не будут присутствовать в перечислении.

Исключения:

IOException - Если произошли ошибки ввода/вывода

С:

1.2

См. также:

findResources(String)

findResource

protected URL findResource(String name)

Ищет ресурс с заданным именем. Реализации загрузчиков классов должны переопределить этот метод, чтобы указать, где искать ресурсы.

Параметры:

name - Имя ресурса

Возвращает:

Объект URL для чтения ресурса или null, если ресурс не найден

С:

1.2

findResources

protected Enumeration<URL> findResources(String name)
                                  throws IOException

Возвращает перечисление объектов URL, представляющих все ресурсы с заданным именем. Реализации загрузчиков классов должны переопределять этот метод, чтобы указать, откуда загружать ресурсы.

Параметры:

name - Имя ресурса

Возвращает:

Перечисление объектов URL для ресурсов

Исключения:

IOException - Если произошли ошибки ввода-вывода

С:

1.2

registerAsParallelCapable

protected static boolean registerAsParallelCapable()

Возвращает:

true, если вызывающий объект успешно зарегистрирован как способный к параллельной работе, и false в противном случае.

С:

1.7

getSystemResource

public static URL getSystemResource(String name)

Находит ресурс с указанным именем из пути поиска, используемого для загрузки классов. Этот метод находит ресурс через системный загрузчик классов (см. getSystemClassLoader()).

Параметры:

name - Имя ресурса

Возвращает:

Объект URL для чтения ресурса или null, если ресурс не найден

С:

1.1

getSystemResources

public static Enumeration<URL> getSystemResources(String name)
                                           throws IOException

Параметры:

name - Имя ресурса

Возвращает:

Перечисление объектов ресурса URL

Исключения:

IOException - Если произошли ошибки ввода-вывода

С:

1.2

getResourceAsStream

public InputStream getResourceAsStream(String name)

Параметры:

name - Имя ресурса

Возвращает:

Поток ввода для чтения ресурса, или null если ресурс не найден

С:

1.1

getSystemResourceAsStream

public static InputStream getSystemResourceAsStream(String name)

Открывает для чтения ресурс с указанным именем из пути поиска, используемого для загрузки классов. Этот метод находит ресурс через системный загрузчик классов (см. getSystemClassLoader()).

Параметры:

name - Имя ресурса

Возвращает:

Поток ввода для чтения ресурса, или null если ресурс не найден

С:

1.1

getParent

public final ClassLoader getParent()

Возвращает:

Родительский ClassLoader

Исключения:

SecurityException - Если менеджер безопасности существует и его метод checkPermission не разрешает доступ к родительскому загрузчику классов этого загрузчика классов.

С:

1.2

getSystemClassLoader

public static ClassLoader getSystemClassLoader()

Возвращает:

Системный ClassLoader для делегирования или null если его нет

Исключения:

SecurityException - Если менеджер безопасности существует и его метод checkPermission не разрешает доступ к системному загрузчику классов.

IllegalStateException - Если вызывается рекурсивно во время создания загрузчика классов, указанного в системной переменной "java.system.class.loader".

Error - Если системная переменная "java.system.class.loader" определена, но указанный класс не удалось загрузить, класс-поставщик не определяет необходимый конструктор или в конструкторе происходит исключение при вызове. Причину ошибки можно получить с помощью метода Throwable.getCause().

definePackage

protected Package definePackage(String name,
                                String specTitle,
                                String specVersion,
                                String specVendor,
                                String implTitle,
                                String implVersion,
                                String implVendor,
                                URL sealBase)
                         throws IllegalArgumentException

Определяет пакет по имени в этом ClassLoader. Это позволяет загрузчикам классов определять пакеты для своих классов. Пакеты должны быть созданы до определения класса, имена пакетов должны быть уникальными в пределах загрузчика классов и не могут быть переопределены или изменены после создания.

Параметры:

name - Имя пакета

specTitle - Заголовок спецификации

specVersion - Версия спецификации

specVendor - Поставщик спецификации

implTitle - Заголовок реализации

implVersion - Версия реализации

implVendor - Поставщик реализации

sealBase - Если не null, то этот пакет запечатан относительно указанного источника кода URL. В противном случае пакет не запечатан.

Возвращает:

Новый объект Package

Исключения:

IllegalArgumentException - Если имя пакета дублирует существующий пакет в этом загрузчике классов или в одном из его предков

С:

1.2

getPackage

protected Package getPackage(String name)

Возвращает Package, определённый этим загрузчиком классов или любым из его предков.

Параметры:

name - Имя пакета

Возвращает:

Package соответствующий данному имени, или null если не найден

С:

1.2

getPackages

protected Package[] getPackages()

Возвращает все Packages определённые этим загрузчиком классов и его предками.

Возвращает:

Массив объектов Package определённых этим ClassLoader

С:

1.2

findLibrary

protected String findLibrary(String libname)

Возвращает абсолютный путь к библиотеке нативных функций. Виртуальная машина вызывает этот метод, чтобы найти нативные библиотеки, относящиеся к классам, загруженным с помощью этого загрузчика классов. Если этот метод возвращает null, виртуальная машина ищет библиотеку по пути, указанному в системной переменной "java.library.path".

Параметры:

libname - Имя библиотеки

Возвращает:

Абсолютный путь к нативной библиотеке

С:

1.2

См. также:

System.loadLibrary(String), System.mapLibraryName(String)

setDefaultAssertionStatus

public void setDefaultAssertionStatus(boolean enabled)

Устанавливает состояние утверждения по умолчанию для этого загрузчика классов. Это значение определяет, будут ли в будущем классы, загруженные этим загрузчиком классов, иметь включённые по умолчанию утверждения или выключены. Это значение может быть переопределено на основе пакета или класса с помощью вызова setPackageAssertionStatus(String, boolean) или setClassAssertionStatus(String, boolean).

Параметры:

enabled - true если классы, загруженные этим загрузчиком классов, в дальнейшем будут иметь включённые по умолчанию проверки, false если они будут иметь отключённые по умолчанию проверки.

С:

1.4

setPackageAssertionStatus

public void setPackageAssertionStatus(String packageName,
                                      boolean enabled)

Параметры:

packageName - Имя пакета, для которого необходимо установить состояние проверки по умолчанию. Значение null указывает на неопределённый пакет, который является «текущим» (см. раздел 7.4.2 спецификации языка Java™).

enabled - true если классы, загруженные этим загрузчиком классов и принадлежащие указанному пакету или любому из его подпакетов, будут иметь проверки включёнными по умолчанию, false если они будут иметь проверки выключенными по умолчанию.

С:

1.4

setClassAssertionStatus

public void setClassAssertionStatus(String className,
                                    boolean enabled)

Параметры:

className - Полное имя класса верхнего уровня, для которого нужно установить состояние проверок.

enabled - true если для указанного класса проверки должны быть включены при (и если) он инициализирован, false если для класса проверки должны быть выключены.

С:

1.4

clearAssertionStatus

public void clearAssertionStatus()

Устанавливает значение состояния проверок по умолчанию для этого загрузчика классов на false и отбрасывает все значения по умолчанию для пакетов или состояния проверок для класса, связанные с загрузчиком классов. Этот метод предоставляется для того, чтобы загрузчики классов могли игнорировать любые командные строки или постоянные настройки состояния проверок и «начинать с чистого листа».

С:

1.4