#07.1 — Maven i eclipse

We wcześniejszych lekc­jach poz­nal­iśmy Mave­na jako narzędzie, dzisi­aj dowiemy się nieco więcej jak skon­fig­urować i uży­wać go w Eclipse.

Dzisiejsza lekc­ja pow­stała na prośbę jed­nego z naszych czytel­ników i omaw­iać będzie szerzej zagad­nienia związane z kon­fig­u­racją i uży­waniem Maven w Eclipse.

Lekcja

Instalacja i wymagania

Aby w ogóle korzys­tać z Maven w środowisku Eclipse musimy najpierw pobrać odpowied­nią wty­czkę. Nazy­wa się ona m2e i jest dostęp­na także poprzez Eclipse Mar­ket­place. Najpraw­dopodob­niej będziesz miała ją już zain­stalowaną, jeśli pobier­ałaś wer­sje Eclipse przez­nac­zoną do web devel­op­men­tu — np. Spring­Tool­Suite. Jeśli nie, najłatwiej sko­rzys­tać z Eclipse Mar­ket­place tak jak poniżej:

Eclipse Mar­ket­place w menu Help

Zain­stalowane mod­uły m2e — moż­na je samodziel­nie zain­stalować wyszuku­jąc je w zakład­ce ‘Search’ pod hasłem m2e

Zarządzanie projektem Maven pod Eclipse

Są trzy możli­woś­ci, jak może­my korzys­tać z dobrodziejstw m2e — pole­cam wyko­rzysty­wać wyłącznie dwie pier­wsze, trze­cia zostanie jedynie wspom­ni­ana i jest przez­nac­zona raczej dla osób doświad­c­zonych z ‘grze­ban­iem’ w Eclipse.

Utwórz nowy projekt / moduł

Ta opc­ja jest dla osób, które dopiero będą pisały kod i chcą, aby pro­jekt był zarządzany za pomocą Maven’a . Z menu File wybier­amy opcję New a następ­nie Oth­er. W oknie, które się pojawi wyszuku­je­my zakład­kę ‘Maven’ i mamy dostęp­ne kil­ka opcji:

Okno File -> New -> Oth­er z rozwiniętą zakład­ką ‘Maven’

Pier­wsza z nich (Check out Maven Projects from SCM) umożli­wia import pro­jek­tu pobier­a­jąc go z repozy­to­ri­um (jak np. Git czy Svn — o nich powiemy sobie w przyszłoś­ci). Dzi­ała ana­log­icznie jak impor­towanie ist­niejącego pro­jek­tu (opisanego poniżej) tyle tylko, że sama pobiera kod z repozy­to­ri­um na dysk.

Dru­ga opc­ja (Maven mod­ule) pozwala na stworze­nie nowego mod­ułu, tzn. pod­pro­jek­tu — takiego, który ma rodz­i­ca. Przykła­dem może być mod­uł związany z obsługą bazy danych w więk­szej aplikacji. W mniejszych pro­jek­tach częs­to ist­nieje podzi­ał na mod­uły wg warstw log­icznych — obsłu­gi danych (np. bazy danych), logi­ki biz­ne­sowej (ser­wisy) oraz prezen­tacji (np. aplikac­ja webowa i wido­ki HTML). W więk­szych częs­to jest to podzi­ał wg dome­ny (np. obsłu­ga kart, obsłu­ga transakcji, obsłu­ga sprzedaży itp).

Trze­cia opc­ja (Maven project) pozwala na utworze­nie nowego pro­jek­tu. Pro­jekt to nadrzęd­na jed­nos­t­ka w Mave­nie, jeden pro­jekt może (ale nie musi) grupować kil­ka modułów.

Kon­fig­u­rac­ja drugiej i trze­ciej opcji jest niemal iden­ty­cz­na, różni się jedynie tym, że w przy­pad­ku mod­ułu w pier­wszym kroku wybier­amy też rodz­i­ca. Scree­ny będą pokazane na przykładzie pro­jek­tu (opc­ja trzecia).

Pier­wszy ekran tworzenia nowego pro­jek­tu Maven

Na pier­wszym ekranie mamy do wyboru kil­ka opcji, związanych bardziej z wyglą­dem w Eclipse niż z dzi­ałaniem m2e:

• Cre­ate sim­ple project (skip arche­type selec­tion) — zaz­nacza­jąc tą opcję pomi­jamy wybór arche­ty­pu (czyli ‘szablonu’ pro­jek­tu, może­my sko­rzys­tać z gotowych lub z utwor­zonych przez nas) i tworzymy pusty pro­jekt. Częs­to zaczy­na­jąc pracę będziemy korzys­tali właśnie z tej opcji, samodziel­nie doda­jąc zależnoś­ci i tworząc struk­turę projektu.
• Use default work­space loca­tion — może­my utworzyć pro­jekt w innym miejs­cu na dysku niż domyśl­ny kat­a­log. Ta opc­ja nie zmienia nic w zachowa­niu m2e, doty­czy jedynie fizy­cznego położe­nia plików na dysku
• Add projects to work­ing set — ta opc­ja pozwala nam na wybranie work­ing set’a, do którego dodamy pro­jekt. Work­ing set to coś w rodza­ju kat­a­logów — może­my pogrupować sobie pro­jek­ty nad który­mi aktu­al­nie pracu­je­my (jest to pomoc­ne, jeśli pracu­je­my nad wielo­ma jed­nocześnie, np. przy dużym projekcie)
• Rozwi­ja­jąc zakład­kę Advanced mamy dodatkowe opc­je, z których ciekawsza jest Name tem­plate — pozwala ona określić, pod jaką nazwą będzie się wyświ­et­lał pro­jekt. Ja pro­ponu­ję [groupId].[artifactId] — dla mnie najlepiej się ona sprawdza, ale jest to bard­zo kwes­t­ia oso­bistych pref­er­encji. Tak, żeby Tobie było wygodnie :)

Dru­gi ekran — kon­fig­u­rac­ja specy­ficz­na dla Maven’a

W drugim kroku kon­fig­u­ru­je­my ustaw­ienia specy­ficzne dla Mave­na. Wyma­gane pola to:

• Group Id i Arti­fact Id — ‘współrzędne’ Mave­na, więcej o nich zna­jdziesz w lekcji #7
• Ver­sion — wer­s­ja naszego pro­jek­tu, najczęś­ciej na początek warto zostaw­ić domyśl­ny numer. Numer­ac­ja wer­sji w Mave­nie ma pewną kon­wencję i skła­da się z następu­ja­cych ele­men­tów (od lewej; ele­men­ty te są opcjon­alne od Minor Version): 
  • Major ver­sion (0.0.1‑SNAPSHOT) — wer­s­ja głów­na, zwięk­sza­my ją jak robimy bard­zo duże zmi­any, np. przepisu­je­my dużą część, zmieni­amy cały (lub więk­szość) inter­fe­js itp
  • Minor ver­sion  (0.0.1‑SNAPSHOT) — wer­s­ja mniejsza, zmieni­amy ją w przy­pad­ku dodania/modyfikacji znaczą­cych funkcjon­al­noś­ci (ale nie wpły­wa­ją­cych na całą aplikację)
  • Incre­men­tal  (0.0.1-SNAPSHOT) — zmieni­amy zawsze, gdy wprowadza­my jakieś nowe rzeczy (najczęś­ciej w przy­pad­ku pro­jek­tów komer­cyjnych zmieni­amy w sytu­acji kiedy udostęp­ni­amy nową wer­sję dla klienta/do pobrania)
  • Build num­ber  (0.0.1-12) — nieczęs­to uży­wana notac­ja (ale nadal zgod­na ze stan­dar­d­em), najczęś­ciej w dużych pro­jek­tach o zau­tomaty­zowanym pro­ce­sie wydawa­nia oprogramowania
  • Qual­i­fi­er  (0.0.1-SNAPSHOT) — to bard­zo wazny ele­ment, ponieważ dodanie kwal­i­fika­to­ra ‑SNAPSHOT oznacza, że jest to wer­s­ja prze­jś­ciowa i (najczęś­ciej) nie do koń­ca gotowa do dzi­ała­nia w środowisku pro­duk­cyjnym. Częs­to też takie wer­sje są wypuszczane częś­ciej, jako podgląd. Przez to niek­tóre repozy­to­ria nie prze­chowu­ją ich (w takich wypad­kach częs­to moż­na skon­fig­urować dodatkowe, osob­ne repozy­to­ri­um na arte­fak­ty z tym klasy­fika­torem). Inny przykład klasy­fika­to­ra to np. ‑beta, ‑alpha itp
• Pack­ag­ing type — określa sposób, w jaki pli­ki w tym module/projekcie będą trak­towane i przetwarzane w pro­ce­sie budowa­nia. Jest kil­ka stan­dar­d­owych typów, z który­mi będziemy się spo­tykać najczęściej: 
  • pom — jeśli chce­my, aby nasz projekt/moduł był rodz­icem dla innych, musimy wybrać ten rodzaj paczkowania
  • jar — ten rodzaj jest przez­nac­zony do aplikacji stand­alone (takie, które do dzi­ała­nia nie wyma­ga­ją nic innego, np ser­w­era aplikacji) oraz bib­liotek (mod­uły naszej aplikacji częs­to trak­tu­je­my właśnie jako bib­liote­ki, które później są wyko­rzysty­wane przez np. aplikację webową lub inny interfejs)
  • war — to paczkowanie tworzy struk­turę kat­a­logów dla pro­jek­tu aplikacji webowej
  • ear — jest to tzw. enter­prise archive, które służy do paczkowa­nia m.in. kom­po­nen­tów EJB, dość rzad­ko spo­tykane, ale moż­na się z nim spotkac w więk­szych projektach

Te infor­ma­c­je są wystar­cza­jące, aby utworzyć nowy pro­jekt. Po kliknię­ciu na ‘Fin­ish’ po chwili powin­niśmy mieć skon­fig­urowany, gotowy do dal­szej pra­cy projekt :)

Importuj projekt/moduł

Ta opc­ja pozwala nam m.in. zaim­por­tować pli­ki źródłowe, które mamy na dysku jako pro­jekt Maven. Po wybra­niu opcji File -> Import i rozwinię­ciu zakład­ki ‘Maven’ mamy dostęp­ne kil­ka opcji.

Okno File->Import z rozwiniętą zakład­ką ‘Maven’

• Pier­wsza opc­ja (Check out Maven Projects from SCM) dzi­ała ana­log­icznie jak wspom­ni­ana wcześniej — pozwala pobrać pli­ki z repozy­to­ri­um kodu i zaim­por­tować je w Eclipse jako pro­jekt Maven
• Dru­ga opc­ja (Exist­ing Maven Projects) będzie dla nas najbardziej przy­dat­na i ją opisze­my szerzej, służy do zaim­por­towa­nia plików, które mamy na dysku i trak­towa­nia ich jako pro­jekt Maven. Oczy­wiś­cie muszą mieć one plik pom.xml oraz struk­turę zgod­ną z Mavenem
• Trze­cia opc­ja (Install or deploy an arti­fact to a Maven repos­i­to­ry) pozwala nam zaim­por­tować arte­fakt (np. plik JAR) do repozy­to­ri­um (co w efek­cie umożli­wi np. korzys­tanie przy pomo­cy Mave­na z bib­liotek, które nie są pub­likowane w ramach Mave­na). Jest to bard­zo przy­dat­na opc­ja w szczegól­noś­ci, jeśli musimy korzys­tać z pro­jek­tów pisanych dawno temu i chce­my uży­wać Mave­na do zarządza­nia nowym pro­jek­tem (Uwa­ga! To impor­tu­je plik tylko do lokalnego repozy­to­ri­um, tj. ktoś inny chcąc u siebie zbu­dować pro­jekt, będzie musi­ał zaim­por­tować te same arte­fak­ty co my do swo­jego repozytorium)
• Czwarta opc­ja (Mate­ri­al­ize Maven Projects from SCM) pozwala na pobranie plików pro­jek­tu i import jego źródeł na dysk z repozy­to­ri­um kodu tylko na pod­staw­ie pliku pom.xml (o ile zaw­iera on infor­ma­c­je o lokaliza­cji repozy­to­ri­um). Opc­ja stosowana dość rzad­ko (oso­biś­cie nie miałem okazji), niem­niej na pewno warto wiedzieć, że istnieje

Skup­my się na drugiej opcji, czyli impor­towa­niu plików, które mamy na dysku do Eclipse. Po wybra­niu tej opcji zobaczymy okno podob­ne do poniższego:

Okno impor­tu pro­jek­tu Maven — na przykładzie widoczny pro­jekt open source web­cam-cap­ture
Notabene autorem tej bib­liote­ki jest nasz rodak, Bar­tosz Firyn, które­mu w tym miejs­cu serdecznie dzięku­je za oszczędze­nie tygod­ni pra­cy, kilkukrotnie :)

Oczy­wiś­cie początkowo głów­na część okna będzie pus­ta — po wyborze ścież­ki w polu Root Direc­to­ry Eclipse przeszuku­je ten kat­a­log i pod­kat­a­lo­gi w poszuki­wa­niu plików pom.xml a następ­nie na tej pod­staw­ie tworzy listę pro­jek­tów, które może­my zaim­por­tować. Może­my wybrać wszys­tkie z nich lub tylko niek­tóre, w zależnoś­ci od potrzeby.

Może­my także ustaw­ić Work­ing set, którego będziemy uży­wać oraz schemat nazewnict­wa (ukry­ty pod opcją ‘Advanced’).

Po kliknię­ciu ‘Fin­ish’ przy­go­tuj się na chwilę czeka­nia, szczegól­nie z więk­szy­mi pro­jek­ta­mi, Eclipse w tym cza­sie pobiera wszys­tkie zależnoś­ci (oraz ich zależnoś­ci), impor­tu­je kod, anal­izu­je go, indek­su­je i pewnie robi masę innych użytecznych rzeczy o których mam niewielkie poję­cie, w każdym razie — chwile to trwa :)

Konwersja projektu na Maven

Ta opc­ja dostęp­na jest z poziomu menu kon­tek­stowego, jako Maven -> Enable Maven Nature lub z sub­menu Con­fig­ure -> Con­vert to Maven Project. Obie te opc­je jed­nak niosą ze sobą pewne ryzy­ka — decy­du­jąc się na ich uży­cie, naprawdę należy być świadomym, co się robi. Ponieważ nie jest to coś, z czym możesz się spotkać na co dzień, nie będziemy zgłębi­ać tego tem­atu, mam nadzieję, że wybaczycie :)

Praca z plikiem pom.xml

Z uży­ciem wty­cz­ki m2e może­my otworzyć plik pom.xml w spec­jal­nym edy­torze. Edy­tor ten podzielony jest na kil­ka zakładek, jak na przykładzie poniżej. Każ­da z tych zakładek została pokrótce omówiona poniżej.

Widok zakład­ki Overview w edy­torze pliku pom.xml

• Overview — tutaj może­my skon­fig­urować ogólne para­me­try pro­jek­tu, takie jak nazwa, rodz­ic, pod­mod­uły, repozy­to­ri­um kodu oraz inne metadane obsługi­wane przez plik pom.xml. W przy­pad­ku mod­ułów warto zwró­cić uwagę na dwa przy­cis­ki zna­j­du­jące się w tej zakładce: 
  • Add pozwala dodać ISTNIEJĄCY moduł/projekt, jako mod­uł tego projektu
  • Cre­ate pozwala utworzyć mod­uł, który będzie przyp­isany do tego projektu
• Depen­den­cies — Tutaj może­my zarządzać zależnoś­ci­a­mi naszego mod­ułu za pomocą prostego edy­to­ra graficznego
• Depen­den­cy Hier­ar­chy — To bard­zo przy­dat­na zakład­ka w przy­pad­ku kon­flik­tów wer­sji (np. potrze­bu­je­my mod­ułu A w wer­sji X, a poprzez inne zależnoś­ci jest on też impor­towany w wer­sji Y) — pozwala nam przede wszys­tkim prze­jrzeć i prze­filtrować wszys­tkie zależnoś­ci, które wys­tępu­ją w naszym mod­ule, jak też wyk­luczać je w razie potrze­by. (Uwa­ga prak­ty­cz­na: fil­trowanie potrafi dzi­ałać bard­zo powoli, szczegól­nie w dużych projektach)
• Effec­tive POM — Kole­j­na z ważnych zakładek do rozwiązy­wa­nia pro­jek­tów, pozwala pode­jrzeć tzw. effec­tive POM — czyli ujed­no­li­cony plik POM po doda­niu wszys­t­kich ele­men­tów z plików POM pro­jek­tów-rodz­iców i określe­niu wartoś­ci wszys­t­kich zmi­en­nych. Tak naprawdę to effec­tive POM decy­du­je o tym, jak pro­jekt jest budowany. Jeśli więc jakieś z ustaw­ień są nad­pisy­wane, moż­na to zwery­fikować właśnie w tym miejscu
• pom.xml — tek­stowa wer­s­ja pliku pom.xml, z cza­sem najczęś­ciej będziesz korzys­tała właśnie z tej zakładki ;)

Rozwiązywanie problemów

Pracu­jąc z pro­jek­ta­mi Maven cza­sem może­my napotkać na pewne drob­ne prob­le­my i bugi. Jest kil­ka sposobów, żeby sobie z nimi poradz­ić, może­my spróbować następu­ja­cych kroków:

1. Nie paniku­je­my ;)
2. Sprawdza­my w czym jest prob­lem — być może zro­bil­iśmy np. literówkę. Może­my to sprawdz­ić w oknie ‘prob­lems’:
3. Na początku próbu­je­my po dobro­ci — wyczyś­cić trochę metadanych i odświeżyć (klikamy prawym przy­ciskiem mysz­ki na pro­jekt i wybier­amy Maven -> Update Project. W oknie, które się pojawi wybier­amy też ‘Force Update of Snapshot/Releases’ i klikamy OK. Ta oper­ac­ja może zająć chwilę
4. Jeśli to nie pomoże, cza­sem pomoc­ne jest usunię­cie pro­jek­tu do Eclipse (uwa­ga, żeby nie zaz­naczyć opcji usuwa­nia także plików) i ponowne zaim­por­towanie go
5. Kole­jnym krok­iem jest wyczyszcze­nie pamię­ci Eclipse pomiędzy usunię­ciem, a ponownym importem w tej kolejności: 
   1. usuwamy pro­jekt
   2. zamykamy Eclipse
   3. uruchami­amy z opcją czyszczenia (jak to zro­bić możesz przeczy­tać tutaj)
   4. zamykamy
   5. uruchami­amy bez opcji czyszczenia
   6. impor­tu­je­my projekt

Cza­sa­mi pojaw­ia się też prob­lem tego rodza­ju, że doda­jąc pro­jekt do ser­w­era aplikacji w Eclipse (np. Tom­ca­ta), otrzy­mu­je­my błąd Class­Not­FoundEx­cep­tion. Cza­sem jest to spowodowane tym, że Eclipse z jakiegoś powodu ‘gubi’ infor­ma­c­je o zależnoś­ci­ach z Mave­na. Najczęś­ciej moż­na to rozwiązać klika­jąc prawym przy­ciskiem mysz­ki na pro­jekt, który spraw­ia prob­le­my i wybier­a­jąc opcję ‘Prop­er­ties’. Następ­nie prze­chodz­imy na zakład­kę Deploy­ment Assembly.

Przykłą­dowa kon­fig­u­rac­ja Deploy­ment Assem­bly dla pro­jek­tu webowego w Mavenie

Upew­ni­amy się, że jest tam pozy­c­ja ‘Maven Depen­den­cies’. Jeśli jej nie ma, wykonu­je­my poniższe kroki:

1. Wybier­amy opcję ‘Add’
2. W oknie, które się pojawi wybier­amy ‘Java Build Path Entries’
3. W kole­jnym oknie wybier­amy Maven Depen­den­cies (całe, a nie któryś z podelementów)
4. Klikamy ‘Fin­ish’

Powyższe dzi­ała­nia powin­ny pomóc w więk­szoś­ci prob­lemów z Maven­em, ale oczy­wiś­cie może się zdarzyć, że natrafisz na inny prob­lem. Warto zapy­tać swoich współpra­cown­ików, być może mieli podob­ny prob­lem, lub napisac do nas — zawsze spróbu­je­my pomóc :)

Podsumowanie

W tej lekcji poz­nal­iśmy trochę Mave­na od strony jego obsłu­gi w Eclipse a także jak radz­ić sobie z najczęst­szy­mi prob­le­ma­mi :) Maven to naprawdę potężne narzędzie i zachę­cam do pogłębia­nia swo­jej wiedzy w tym zakresie!

Materiały dodatkowe / dokumentacja

1. Opis schematu wer­sjonowa­nia Maven w doku­men­tacji jed­nego z pro­duk­tów Ora­cle (EN)
2. Wstęp do m2e (EN)