Pakiet javax.servlet jest jądrem Servlet API. Zawiera on podstawowy interfejs Servlet, który musi być implementowany w tej czy innej formie przez wszystkie serwlety oraz abstrakcyjną klasę GenericServlet służącą do tworzenia prostych serwletów. Zawiera on również klasy służące do komunikowania się z serwerem i klientem komputera (ServletRequest i ServletResponse) oraz komunikowania z klientem (ServletInputStream i ServletOutputStream). Hierarchia klas pakietu javax.servlet jest przedstawiona na rysunku A.1. Serwlety powinny graniczyć z klasami tego pakietu w sytuacjach, w których nieznany jest leżący poniżej protokół.
Rysunek A.1.
Pakiet javax.servlet
Nazwa Klasy
javax.servlet.GenericServlet
Superklasa
java.lang.Object
Bezpośrednie podklasy
javax.servlet.http.HttpServet
Implementowane interfejsy
javax.servlet.Servlet
javax.servlet.ServletConfig
java.io.Serializable
Dostępność
Servlet API 1.0 i późniejsze
GenericServlet dostarcza podstawowej implementacji interfejsu Servlet dla serwletów niezależnych od protokołu. Jako ułatwienie implementuje ona również interfejs ServletConfig. Większość programistów serwletów tworzy swoje klasy jako podklasy tej klasy lub HttpServlet, zamiast bezpośrednio implementować interfejs Servlet.
GenericServlet zawiera podstawowe wersje metod init() i destroy(), które wykonują podstawowe zadania tworzenia i czyszczenia, takie jak zarządzanie obiektem serwera ServletConfig. Serwlet omija jedną z tych metod powinien wywoływać wersje tych metod pochodzące z superklasy. GenericServlet zawiera również metody log() umożliwiające dostęp do funkcji zapisujących dane w dzienniku pochodzących z ServletContext.
Metoda service() jest deklarowana abstrakcyjnie musi zostać ominięta. Dobrze napisane serwlety omijają również getServletInfo().
public abstract class GenericServlet
implements Servlet, ServletConfig, java.io.Serializable {
// Konstruktory
public GenericServlet()
// Metody egzemplarzy
public void destroy();
public String getInitParameter(String name);
public Enumeration getInitParameterNames();
public ServletConfig getServletConfig();
public ServletContext getServletContext();
public String getServletInfo();
public String getServletName(); // Nowość w 2.2
public void init() throws ServletException; // Nowość w 2.1
public void init(ServletConfig konfig) throws ServletException;
public void log(String wiad);
public void log(String wiad, Throwable t); // Nowość w 2.1
public abstract void service(ServletRequest zad, ServletResponse odp)
throws ServletException, IOException;
}
Domyślny konstruktor GenericServlet() nie wykonuje żadnej pracy. Wszystkie zadania związane z inicjalizacją serwletu powinny być wykonywane w init(), a nie w konstruktorze.
public void destroy()
Wywoływane przez kontener serwletów, aby wskazać serwletowi, że został on wyłączony. Metoda ta jest wywoływana jedynie po wyłączeniu wszystkich wątków wewnątrz metody usługowej serwletu lub po określonym czasie. Po wywołaniu tej metody przez kontener serwletów, nie będzie wywoływał on już metody usługowej serwletu. Domyślna implementacja zapisuje zniszczenie serwletu w dzienniku przy pomocy metody log(). Serwlet może ominąć tę metodę w celu zachowania jej stanu, uwolnienia jej zasobów (połączenia z bazami danych, wątki, uchwyty plików itd.) itp.
public String getInitParameter(String nazwa)
Zwraca wartość danego parametru inicjacji serwletu lub null, jeżeli nie odnajdzie pasujących parametrów. Pochodzi z interfejsu ServletConfig.
public Enumeration getInitParameterNames()
Zwraca nazwy wszystkich parametrów inicjacji serwletu jako Enumeration obiektów String lub pustą Enumeration, jeżeli nie występują żadne parametry. Pochodzi z interfejsu ServletConfig.
public ServletConfig getServletConfig()
Zwraca obiekt ServletConfig serwletu. W praktyce, metoda ta jest rzadko wywoływana przez GenericServlet ponieważ wszystkie metody ServletConfig są wewnętrznie duplikowane.
public ServletContext getServletContext ()
Zwraca obiekt ServletContext serwletu. Pochodzi z interfejsu ServletConfig.
public String getServletInfo()
Zwraca zdefiniowany przez programistę łańcuch String opisujący serwlet. Serwlet powinien omijać tę metodę i dostarczać własnego łańcucha identyfikacyjnego (na przykład „Serwlet Wiadomości Janka v.1.21”), ale nie jest to wymagane.
public String getServletName()
Zwraca nawę aktualnego egzemplarza serwletu. Nazwa może być dostarczona prze administrację serwera lub przypisana w deskryptorze aplikacji WWW, lub, w przypadku niezarejestrowanego (i w związku z tym nienazwanego) egzemplarza serwletu, będzie równa nazwie klasy serwletu. Pochodzi z interfejsu ServletConfig. Metoda ta została wprowadzona w Servlet API 2.2.
public void init() throws ServletException
public void init(ServletConfig konfig) throws ServletException
Wywoływana przez kontener serwletów po pierwszym pobraniu serwletu i przed wywołaniem jego metody service(). Serwlet może omijać tę metodę w celu przeprowadzenia jednorazowej konfiguracji, stworzenia zasobów i tak dalej. Serwlety utworzone według Servlet API 2.1 lub późniejszego mogą implementować wersję bez argumentów. Serwlety, które muszą być kompatybilne wstecz z Servlet API 2.0 powinny implementować wersję pobierającą parametr ServletConfig. Nie należy implementować obu wersji. Domyślna implementacja init() zapisuje w dzienniku inicjalizację serwletu oraz przechowuje obiekt ServletConfig w celu wykorzystania go przez metody interfejsu ServletConfig. Serwlet implementujący wersję pobierającą ServletConfig musi wywołać super.init(konfig) przed wykonaniem własnego kodu inicjacji. Serwlety korzystające z nowej bezargumentowej wersji nie muszą się tym przejmować.
public void log(String wiad)
public void log(String wiad, Throwable t)
Zapisuje daną wiadomość w dzienniku serwletu po nazwie serwletu wywołującego. Miejsce zapisu jest zależne od serwera, zazwyczaj jest to dziennik zdarzeń.
Wywoływana w celu obsłużenia pojedynczego żądania klienta. Serwlet otrzymuje informacje żądania poprzez obiekt ServletRequest i odsyła dane poprzez obiekt ServletResponse. Jest to jedyna metoda, która musi zostać ominięta podczas rozszerzania GenericServlet.
Nazwa interfejsu
javax.servlet.RequestDispatcher
Superinterfejs
Brak
Bezpośrednie podinterfejsy
Implementowany przez
Servlet API 2.1 i późniejsze
Interfejs obiektu, który może wewnętrznie rozsyłać żądania do dowolnych zasobów (takich jak serwlety, pliki HTML lub pliki JSP) na serwerze, Kontener serwletów tworzy obiekt RequestDispatcher, który następnie wykorzystywany jest jako obwódka wokół zasobu serwera umieszczonego w konkretnej ścieżce lub posiadającego konkretną nazwę. Interfejs ten został zaprojektowany w celu wykorzystania z serwletami i plikami JSP, ale kontener serwletów może utworzyć obiekty RequestDispatcher służące jako obwódki dowolnego typu zasobu. Rozsyłanie może zostać wykorzystane do przekazania żądania do zasobu lub do dołączenia zawartości tego zasobu do aktualnej odpowiedzi. Klasa ta została wprowadzona w Servlet API 2.1.
public interface RequestDispatcher {
//Metody
public abstract void forward(ServletRequest zad, ServletResponse odp)
throws ServletException, java.io.IOException // Nowość w 2.1.
public abstract void include(ServletRequest zad, ServletResponse odp)
throws ServletException, java.io.IOException
Przekazuje żądanie z serwletu do innego zasobu na serwerze. Metoda ta pozwala jednemu serwletowi na wykonanie wstępnego przetwarzania żądania, po czym innemu na wygenerowanie odpowiedzi. W przypadku RequestDispatcher otrzymanego przez getRequestDispatcher(), obiekt ServletRequest posiada elementy ego ścieżki i parametry dołączone w celu dopasowania ścieżki zasobu docelowego. Metoda ta powinna zostać wywołana przed wysłaniem odpowiedzi do klienta. Jeżeli odpowiedź została już wysłana, metoda wywołuje wyjątek IllegalStateException. Niewysłana zawartość w buforze odpowiedzi zostaje automatycznie wyczyszczona przed przekazaniem. Parametry żądania i odpowiedzi muszą być tymi samymi obiektami, które zostały przekazane metodzie usługowej serwletu wywołującego. Metoda ta została wprowadzona w Servlet API 2.1.
Dołącza zawartość zasobu do aktualnej odpowiedzi. Elementy ścieżki i parametry ServletRequest pozostają niezmienione w porównaniu z zasobem wywołującym; jeżeli dołączane zasoby wymagają dostępu do swoich własnych elementów i parametrów, może odczytać je przy pomocy przypisanych do serwera atrybutów żądania javax.servlet.include.request_uri, javax.servlet.include.context_path, javax.servlet.include.path_info i javax.servlet.include.query_string. Dołączony serwlet nie może zmieniać kodu stanu odpowiedzi ani ustawiać nagłówków; każda próba zmiany jest ignorowana. Parametry żądania i odpowiedzi muszą być tymi samymi obiektami, które zostały przekazane metodzie usługowej serwletu wywołującego. Metoda został wprowadzona w Servlet API 2.1.
Wszystkie serwlety implementują interfejs Servlet, czy to bezpośrednio, czy poprzez podklasę GenericServlet lub HttpServlet. Większość programistów serwletów uważa za łatwiejsze uczynienie serwletu podklasą jednej z dwóch istniejących klas serwletów niż bezpośrednią implementację tego interfejsu. Interfejs deklaruje podstawową funkcjonalność serwletów — inicjowanie serwletu, obsługę żądania klienta i niszczenie serwletu.
public interface Servlet {
// Metody
public abstract void destroy();
public abstract ServletConfig getServletConfig();
public abstract String getServletInfo();
public abstract void init(ServletConfig konfig) throws ServletException;
public abstract void destroy()
Wywoływana przez kontener serwletów w celu wskazania serwletowi, że został wyłączony. Proszę zobaczyć pełny opis w GenericServlet.
public abstract ServletConfig getServletConfig()
Zwraca obiekt ServletConfig zapamiętany przez metodę init().
public abstract String getServletInfo()
Zwraca zdefiniowany przez programistę łańcuch String opisujący serwlet.
public abstract void init(ServletConfig konfig) throws ServletException
Wywoływana przez kontener serwletów w po pierwszym załadowaniu serwletu i przed wywołaniem metody service() serwletu. Proszę zobaczyć pełny opis w GenericServlet.
throws ServletException, IOException
Wywoływana w celu obsłużenia pojedynczego żądania klienta. Serwlet otrzymuje informację o żądaniu przez obiekt ServletRequest i wysyła dane z powrotem do klienta przez obiekt ServletResponse.
Kontenery serwletów wykorzystują obiekty ServletConfig do przekazywania serwletom informacji o inicjacji i kontekście. Informacje inicjacji ogólnie składają się z serii parametrów inicjacji i obiektu ServletContext dostarczającego informacji na temat środowiska serwletu. Serwlet może zaimplementować ServletConfig w celu ułatwienia dostępu do parametrów inicjacji i informacji o kontekście, jak to robi GenericServlet.
public interface ServletConfig {
public abstract String getInitParameter(String nazwa);
public abstract Enumeration getInitParameterNames();
public abstract ServletContext getServletContext();
public abstract String getServletName(); // Nowość w 2.2
public abstract String getInitParameter(String nazwa)
...
Ksiundz