source: branches/irods-mockup/doc/qcg-icon.txt @ 142

==========
 QCG-Icon
==========

Adres svn: https://apps.man.poznan.pl/svn/qcg-icon

Na SVN-ie jest projekt dla NetBeans; uÅŒywałem NB 7.0.1, w 7.1 działa i zaznacza kilka nowych warningów typu kolejność importów.
Większość GUI jest zrobiona przy uÅŒyciu wbudownaego w NetBeans edytora formatek.

Opis działania
==============

UÅŒytkownik instaluje program:
Do katalogu trafiają:
- QCG-Icon.jar
- lib\
- resources\                         - zasoby; w tej chwili tylko ikony 
- certs\                             - certyfikaty; w tej chwili CA PL-Gridu
- ( qcg-icon.exe | qcg_icon.sh | ? ) - launcher do QCG-Icon.jar (win|lin|mac)
- config.properties                  - w tej chwili dwa ustawienia 1) jakim poleceniem uruchomić główne okno 2) jak duÅŒymi fragmentami pobierać pliki wyjściowe
- urls.properties                    - opis zasobów (patrz przykład na SVN'ie)
- logging.properties                 - reguły logowania
- ( uninst.exe | - | ? )             - deinsalator
(Windows) Do rejestru trafiają:
- HKCR\< obsługiwane rozszerzenia, eg .gjf >\shell\submit\command   - dodaje akcję do menu kontekstowego dla rozszerzenia
- HKCU\Software\Microsoft\Windows\CurrentVersion\Run\QCG-Icon       - włącza autostart (jeśli uÅŒytkownik wybrał)
(Windows) Do menu trafia:
- Wszystkie programy\qcg-icon.lnk                                   - skrót do Icon


UÅŒytkownik uruchamia program pierwszy raz:
- odpalana jest klasa Main
- sprawdzane są argumenty, patrz nested klasa Main.Args
- (zakładam brak argumentów)
- stwierdzono brak plików %HOME%/.qcg-icon/user(cert|key).pem
- uruchamia się okno CertificateFromP12ToPem
- uÅŒytkownik podaje certyfikat i hasło, certyfikat jest konwertowany
- uruchamia się głowne okno (klasa MainFrame)

UÅŒytkownik zleca zadane:
- odpalana jest klasa Main
- odpalana jest klasa NewTask
- odczytywany jest urls.properties i .qcg-appcache (klasa ResourceList)
- odczytywany jest plik .qcg-icon-prefs, pola są usupełniane odczytanymi wartościami
- uÅŒytkownik wypełnia pola
- klika 'sprawdź dostępność':
 - podaje hasło do certyfikatu
 - ściągany jest nowszy plik urls.properties z http://grass1.man.poznan.pl/qcg-icon/urls.properties
 - kaŌdy zasób jest pytany o FactoryAttributeDocuments
 - wyniki są zapisywane w %HOME%/.qcg-icon/.qcg-appcache
 - uaktualnienie GUI
- uÅŒytkownik klika 'skrypty':
 - nowe okno
 - wpisuje poprawne ścieÅŒki lub wybiera przyciskiem przeglądaj
- klika zleć zadanie
- zapisywany jest plik .qcg-icon-prefs
- IPC: submit próbuje się skontaktować z głównym procesem
 - z java preferences odczytywany jest port na którym ostatnio było główne okno (lub -1)
 - otwierane jest połącznie localhost:port
 - odczytywany jest magiczny numer (ÅŒeby sprawdzić co jest po drugiej stronie)
 - przesyłany jest opis zadania - klasa TaskDescription
 - koniec programu
- jeśli nie ma komunikacji z głównym procesem, jest on na nowo spawnowany

Zlecenie zadania od strony MainFrame, zaczynając od uruchomienia:
- uruchamia się Main
- IPC: okno głowne sprawdza czy nie ma innego okna
 - z java preferences odczytywany jest port na którym ostatnio było główne okno (lub -1)
 - otwierane jest połącznie localhost:port
 - odczytywany jest magiczny numer (ÅŒeby sprawdzić co jest po drugiej stronie)
 - okno juÅŒ działa, koniec procesu.
- (proces jest jedynym Iconem)
- tworrzony jest obiekt MainFrame
- konstruktor tworzy nowy wątek, otwiera server socket
- zapisuje do preferencji port na którym słucha
- wczytywane są zadania z pliku %HOME%/.qcg-icon/.qcg-icon-tasks
- przychodzi połączenie
- odbierany jest opis zadania (TaskDescription)
- tworzone jest okno SubmitTask
 - okno zleca zadanie tworząc obiekt Task
 - wywoływany jest callback na główne okno
- zadanie jest dodane do listy
- zadanie jest dodane do TaskPolling
- TaskPolling okresowo wywołuje checkState
- checkState wykrywa zmianę stanu -> zmienia GUI 
- checkState wykrywa zakończenie -> woła taskFinished
- jeśli wyniki są ściągane automatycznie, uruchamiane jest fetchResults

Dostęp do stubów QCG:
- klasa Main tworzy QcgStubsKeeper i przekazuje dalej
- odwołanie do getFactory / getStaging klasy QcgStubsKeeper
- jeśli nie ma obiekty gsiAuthentication, lub jeśli wymuszono pytanie:
 - uÅŒytkownk jest pytany o hasło
 - tworzony jest obiekt gsiAuthentication
- jeśli nie ma, przygotowywany jest stub factory / staging
- zwracany jest stub factory / staging

Instalatory
===========
Windows:
- ant jar (albo clean&buld w NetBeans)
- launch4j tworzy z pliku launch4j_qcg-icon.xml plik exe sprawdzający wersję Javy i uruchamiający QCG-Icon.jar z odpowiednimi parametrami
- NSIS tworzy z installer.nsi instalator (uwaga na ścieÅŒkę do instalatora, prawdopodobnie C:\)

Linux:
- uruchomić makeLinuxDist.sh

Mac:
?

Opis klas
=========

TaskDescription
~~~~~~~~~~~~~~~
Opis zadania, tworzony w momencie kiedy uÅŒytkownik zleca zadanie.
Zawiera to co uÅŒytkownik wybrał w oknie zlecania zadania.
Nie jest zmieniany w trakcie działania.

Task
~~~~
Reprezentuje zlecone zadanie. Zawiera obiekt klasy TaskDescription i pola opisujące zadanie w usłudze QCG i stan zadania.
Pola uzupełniane / zmieniane w trakcie działania.
Zawiera metodę pobierającą czas następnego sprawdzenia stanu.

TaskDatabase
~~~~~~~~~~~~
Trzyma informacje o zadaniach. W bieŌącej chwili na dysku, uÅŒywając serializacji Javy.

ResourceList
~~~~~~~~~~~~
Wczytuje plik urls.properties opisujący zasoby i aplikacje.
Zawiera statyczne klasy ResourceList.Resource i ResourceList.Application opisujące przeczytane z konfiguracji zasoby i aplikacje.
Klasa uÅŒywana do pamiętania jakie aplikacje są dostępne na konkretnych zasobach (appCache).

Utils
~~~~~
Grupa metod statycznych do róŌnych zadań, m. inn.:
- obsługa autostartu
- look and feel, centrowanie okna
- tworzenie plików zip
- usuwanie zdalnego katalogu, kopiowanie zdalnego katalog lokalnie, ściąganie plików
- otwarcie edytora tekstowego i managera plików
- opakowanie Runnable w okno z paskiem postępu, konwersja rozmiaru pliku na tekst
- ...

TaskPolling
~~~~~~~~~~~
Zarządza autmatycznym sprawdzaniem stanu zadań

QcgStubsKeeper
~~~~~~~~~~~~~~
Trzyma wszystkie obiekty związane z QCG Comp SDK, autmoatycznie je tworzy jeśli nie istnieją i umoÅŒliwia wymuszone odświeÅŒenie stubów.
Przechowuje dane uwierzytelniające (obiekt z klasy GSIAuthentication)

CertificateFromP12ToPem
~~~~~~~~~~~~~~~~~~~~~~~
Konwertuje .p12 do .pem

GenerateGsiProxy
~~~~~~~~~~~~~~~~
Tworzy certyfikat proxy

Main
~~~~
Punkt wejścia do programu.
Ustawia ścieÅŒki, zmienne środowiskowe, wczytuje argumenty i uruchamia NewTask lub MainFrame.
Jeśli ma uruchmić MainFrame, sprawdza czy główne okno juÅŒ działa, jeśli tak - pokazuje je.

NewTask
~~~~~~~~~~~~
Okno zlecenia nowego zadania.
MoÅŒe być otwarte z:
- klasy Main (jako osobna aplikacja)
- klasy MainFrame

Metody związane z ładowaniem danych do / z GUI:
- NewTask_common (wołane przez konstruktor) uzupełnia GUI domyślnymi danymi
- restoreSettingsFromProps ustawia dane w oknie na podstawie obiektu Properties
- regeneratePropsFromTaskDescr ustawia dane w obiekcie Properties na podstawie ustawień w oknie (pośrednio przez TaskDescr)
- validateByHand sprawdza czy ustawienia w oknie są poprawne, np. walltime nie jest równy 0

SubmitTaskDialog
~~~~~~~~~~~~~~~~
Zleca zadanie na zasób. Pokazuje okno postępu.

ResubmitTaskDialog
~~~~~~~~~~~~~~~~~~
Ponawia zlecenie wybranych przez uÅŒytkownika zadań. Część logiki powtórzona z SubmitTaskDialog, jednak ze zmienionymi szczegółami.

MainFrame
~~~~~~~~~~~~
Główne okno.

WaÅŒniejsze niepozorne zmienne i klasy:
- externalSettings - wczytany plik config.properties
- prefs - preferencje uÅŒytkownika, zapisane jako JavaPreferences
- taskListActionListener - reaguje na akcje z popup menu przy jednym zadaniu
- MultiTaskPopupActions - reaguje na akcje z popup menu przy wielu zadaniach
- model - model listy zadań

Proponuję na początek zwinąć cały kod (ppm w edytorze tekstowym / code folds / collapse all java code) i przeczytać komentarze przed zmiennymi i metodami.

OutputPreview
~~~~~~~~~~~~~~
Podgląd stdout i stderr.

ConfigurationDialog
~~~~~~~~~~~~~~~~~~~~
Okno z ustawieniami

AboutDialog
~~~~~~~~~~~
Okno about

SynchronousTaskMonitor
~~~~~~~~~~~~~~~~~~~~~~
Klasa na potrzeby Piotra, uruchamiana jeśli przy zlecaniu zadania poda się przełącznik -s.
Wtedy proces systemowy zostanie zamknięty po zakończeniu zadania, a nie zleceniu zadania.
Od zlecenia do zakończenia pokazwane jest okno SynchronousTaskMonitor.