НАЗВА

       guestfs-java — як користуватися libguestfs з коду на Java

КОРОТКИЙ ОПИС

        import com.redhat.et.libguestfs.*;

        GuestFS g = new GuestFS ();
        g.add_drive ("disk.img",
                     new HashMap<String,Object>() {
                       {
                           put ("readonly", Boolean.TRUE);
                           put ("format", "raw");
                       }
                     });
        g.launch ();

ОПИС

       На цій сторінці підручника наведено документацію щодо викликів libguestfs з коду мовою
       програмування Java. На сторінці задокументовано відмінності від програмного інтерфейсу C
       та подано декілька прикладів. Якщо ви не дуже знайомі із користуванням libguestfs, вам
       також слід прочитати підручник з guestfs(3).

   ЗАКРИТТЯ ДЕСКРИПТОРА
       Дескриптор закривається, коли його вилучає засіб збирання сміття у системі. Оскільки
       дескриптори libguestfs у значній мірі керуються станами, можна закрити (і отже, звільнити)
       дескриптор явним чином, викликавши метод "close".

   ВИНЯТКИ
       Помилки функцій libguestfs пов'язуються із виключенням "LibGuestFSException". Виключення
       містить єдиний параметр, яким є повідомлення про помилку (параметр "String").

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

       Якщо у прив'язках станеться помилка malloc(3) або якоїсь іншої функції отримання пам'яті,
       буде надіслано виключення "LibGuestFSOutOfMemory".

   ПОДІЇ
       З боку Java реалізовано повну підтримку програмного інтерфейсу подій libguestfs. Створіть
       клас, який реалізує інтерфейс "EventCallback", створіть екземпляр цього класу, а потім
       викличте метод "GuestFS#set_event_callback" для реєстрації цього екземпляра. Метод "event"
       класу викликається, коли libguestfs створює повідомлення про подію.

       Наприклад, такий код виводить усі події трасування:

        GuestFS g = new GuestFS ();
        g.set_trace (true);
        g.set_event_callback (
          new EventCallback () {
            public void event (long event, int eh,
                               String buffer, long[] array) {
              System.out.println (GuestFS.eventToString (event) +
                                  ": " + buffer);
            }
          },
          GuestFS.EVENT_TRACE);
        g.add_drive_ro ("disk.img");
        // тощо

       Виведені дані будуть подібними до таких:

        EVENT_TRACE: add_drive_ro "disk.img"
        EVENT_TRACE: add_drive_ro = 0
        // тощо

   НЕОБОВ'ЯЗКОВІ АРГУМЕНТИ
       Деяким методам передається необов'язкова карта додаткових параметрів. Прикладом таких
       методів є метод "g.add_drive", який можна викликати в один з двох способів:

        g.add_drive ("disk.img");

       або за допомогою додаткових аргументів:

        Map<String, Object> optargs =
          new HashMap<String, Object>() {
          {
            put ("readonly", Boolean.TRUE);
            put ("format", "raw");
          }
        };
        g.add_drive ("disk.img", optargs);

       Щоб дізнатися більше про цю тему, див. "ВИКЛИКИ ІЗ НЕОБОВ'ЯЗКОВИМИ АРГУМЕНТАМИ".

       Необов'язкові параметри дескриптора

       При створенні дескриптора ви також можете передати карту необов'язкових параметрів:

        Map<String, Object> optargs =
          new HashMap<String, Object>() {
          {
            put ("close_on_exit", Boolean.FALSE);
            put ("environment", Boolean.TRUE);
          }
        };
        GuestFS g = new GuestFS (optargs);

       Докладніший опис можна знайти тут: "guestfs_create_flags" in guestfs(3).

ЗБИРАННЯ І ЗАПУСК

       Libguestfs для Java є розширенням Java Native Interface (JNI), яке поділено на три
       частини:

       libguestfs.jar
       libguestfs-ВЕРСІЯ.jar
           Файл JAR з кодом суто Java, який містить декілька класів, основним з яких є
           "com.redhat.et.libguestfs.GuestFS". У основній гілці розробки назва файла JAR містить
           номер версії, але у деяких дистрибутивах Linux файл перейменовують так, щоб у назві не
           було номера версії.

       libguestfs_jni.so
           Код JNI (написаний на C). Ця частина містить приватні функції інтерфейсу між кодом
           Java і звичайною бібліотекою libguestfs, яку написано на C. Вам не слід викликати ці
           функції безпосередньо.

       libguestfs.so
           Типова бібліотека C libguestfs.

       Для збирання вашої програми мовою Java вам слід встановити розташування файла JAR і додати
       його до шляху до класів. Приклад:

        export CLASSPATH=/usr/share/java/libguestfs.jar
        javac MyProgram.java

       Для запуску вашої програми Java вам також потрібно впевнитися, що файл JAR перебуває у
       каталозі зі шляху до класів, а також є частиною вашої програми. Приклад:

        export CLASSPATH=.:/usr/share/java/libguestfs.jar
        java MyProgram

ПРИКЛАД 1. СТВОРЕННЯ ОБРАЗУ ДИСКА

       @EXAMPLE1@

ПРИКЛАД 2. ПЕРЕВІРКА ОБРАЗУ ДИСКА ВІРТУАЛЬНОЇ МАШИНИ

       @EXAMPLE2@

ТАКОЖ ПЕРЕГЛЯНЬТЕ

       guestfs(3), guestfs-examples(3), guestfs-erlang(3), guestfs-gobject(3), guestfs-golang(3),
       guestfs-lua(3), guestfs-ocaml(3), guestfs-perl(3), guestfs-python(3), guestfs-recipes(1),
       guestfs-ruby(3), http://libguestfs.org/, http://caml.inria.fr/.

АВТОРИ

       Richard W.M. Jones ("rjones at redhat dot com")

АВТОРСЬКІ ПРАВА

       © Red Hat Inc., 2011–2012

LICENSE

BUGS

       To get a list of bugs against libguestfs, use this link:
       https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools

       To report a new bug against libguestfs, use this link:
       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools

       When reporting a bug, please supply:

       •   The version of libguestfs.

       •   Where you got libguestfs (eg. which Linux distro, compiled from source, etc)

       •   Describe the bug accurately and give a way to reproduce it.

       •   Run libguestfs-test-tool(1) and paste the complete, unedited output into the bug
           report.