Dodatek A.

Krótki opis Servlet API

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

GenericServlet

Zestawienie

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

Opis

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().

Podsumowanie klasy

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;

}

Konstruktory

GenericServlet()

public GenericServlet()

Domyślny konstruktor GenericServlet() nie wykonuje żadnej pracy. Wszystkie zadania związane z inicjalizacją serwletu powinny być wykonywane w init(), a nie w konstruktorze.

Metody egzemplarzy

destroy()

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.

getInitParameter()

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.

getInitParameterNames()

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.

getServletConfig()

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.

getServletContext()

public ServletContext getServletContext ()

Zwraca obiekt ServletContext serwletu. Pochodzi z interfejsu ServletConfig.

getServletInfo()

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.

getServletName()

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.

init()

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ć.

log()

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ń.

service()

public abstract void service(ServletRequest zad, ServletResponse odp)

throws ServletException, IOException;

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.

RequestDipatcher

Zestawienie

Nazwa interfejsu	javax.servlet.RequestDispatcher
Superinterfejs	Brak
Bezpośrednie podinterfejsy	Brak
Implementowany przez	Brak
Dostępność	Servlet API 2.1 i późniejsze

Opis

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.

Deklaracja interfejsu

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 // Nowość w 2.1.

}

Metody

forward()

public abstract void forward(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.

include()

public abstract void include(ServletRequest zad, ServletResponse odp)

throws ServletException, java.io.IOException

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.

Servlet

Zestawienie

Nazwa interfejsu	javax.servlet.Servlet
Superinterfejs	Brak
Bezpośrednie podinterfejsy	Brak
Implementowany przez	javax.servlet.GenericServlet
Dostępność	Servlet API 1.0 i późniejsze

Opis

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.

Deklaracja interfejsu

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 service(ServletRequest zad, ServletResponse odp)

throws ServletException, IOException;

}

Metody

destroy()

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.

getServletConfig()

public abstract ServletConfig getServletConfig()

Zwraca obiekt ServletConfig zapamiętany przez metodę init().

getServletInfo()

public abstract String getServletInfo()

Zwraca zdefiniowany przez programistę łańcuch String opisujący serwlet.

init()

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.

service()

public abstract void service(ServletRequest zad, ServletResponse odp)

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.

ServletConfig

Zestawienie

Nazwa interfejsu	javax.servlet.ServletConfig
Superinterfejs	Brak
Bezpośrednie podinterfejsy	Brak
Implementowany przez	javax.servlet.GenericServlet
Dostępność	Servlet API 1.0 i późniejsze

Opis

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.

Deklaracja interfejsu

public interface ServletConfig {

// Metody

public abstract String getInitParameter(String nazwa);

public abstract Enumeration getInitParameterNames();

public abstract ServletContext getServletContext();

public abstract String getServletName(); // Nowość w 2.2

Metody

getInitParameter()

public abstract String getInitParameter(String nazwa)

Zwraca wartość danego parametru inicjacji serwletu lub null, jeżeli nie odnajdzie pasującego parametru.

getInitParameterNames()

public abstract Enumeration getInitParameterNames()

Zwraca nazwy wszystkich parametrów inicjacji serwletu jako Enumeration obiektów String, lub pustą Enumeration, jeżeli nie występują żądne parametry.

getServletContext()

public abstract ServletContext getServletContext()

Zwraca obiekt ServletContext wywołującego ją serwletu, umożliwiając interakcję z kontenerem serwletów.

getServletName()

public abstract 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.

ServletContext

Zestawienie

Nazwa interfejsu	javax.servlet.ServletContext
Superinterfejs	Brak
Bezpośrednie podinterfejsy	Brak
Implementowany przez	Brak
Dostępność	Servlet API 1.0 i późniejsze

Opis

Interfejs ServletContext definiuje zbiór metod wykorzystywanych do komunikacji z kontenerem serwletów w sposób niezależny od żądania. Oznacza to odnajdywanie informacji o ścieżce, uzyskiwanie dostępu do innych serwletów działających na serwerze i zapis w pliku dziennika serwera. Każda aplikacja WWW posiada inny kontekst serwletów.

Deklaracja interfejsu

public interface ServletContext {

// Metody

public abstract Object getAttribute(String nazwa);

public abstract Enumeration getAttributeNames(); // Nowość w 2.1

public abstract ServletContext getContext(String sciezkauri); // Nowość w 2.1

public abstract String getInitParameter(String nazwa); // Nowość w 2.2

public abstract Enumeration getInitParameterNames(); // Nowość w 2.2

public abstract int getMajorVersion(); // Nowość w 2.1

public abstract String getMimeType(string plik);

public abstract int getMinorVersion(); // Nowość w 2.1

public abstract RequestDispatcher getNamedDispatcher(String nazwa); // Nowość w 2.2

public abstract String getRealPath(String sciezka);

public abstract URL getResource(String sciezka) // Nowość w 2.1

throws MalformedURLException;

public abstract InputStream getResourceAsStream(String sciezka); // Nowość w 2.1

public abstract String getServerInfo();

public abstract Servlet getServlet(String nazwa) // Opuszczona

throws ServletException;

public abstract Enumeration getServletNames(); // Opuszczona

public abstract Enumeration getServlets(); // Opuszczona

public abstract void log(Exception wyjatek, String wiad); // Opuszczona

public abstract void log(String wiad);

public abstract void log(string wiad, Throwable t); // Nowość w 2.1

public abstract void removeAttribute(String nazwa); // Nowość w 2.1

public abstract void setAttribute(String name, Object o); // Nowość w 2.1

}

Metody

getAttribute()

public abstract Object getAttribute(String nazwa)

Zwraca wartość nazwanego atrybutu kontekstu jako Object lub null, jeżeli atrybut nie istnieje. Atrybuty zależne od serwera mogą zostać automatycznie ustawione przez kontener serwletów w celu dostarczenia serwletom informacji o zakresie dużo szerszym niż dostarczany przez podstawowy Servlet API. Atrybuty mogą też być ustawiane programowo przez serwlety jako sposób dzielenia informacji wewnątrz aplikacji WWW reprezentowanej przez dany kontekst. Nazwy atrybutów powinny być zgodne z tą samą konwencją, co nazwy pakietów. Nazwy pakietów java.* i sun.* są zarezerwowane przez dział Java Software firmy Sun Microsystems (dawniej znany jako JavaSoft), a com.sun.* jest zarezerwowany dla użytku firmy Sun Microsystems. Proszę przejrzeć dokumentację serwera w celu obejrzenia listy wbudowanych atrybutów. Proszę pamiętać, że serwlety oparte na atrybutach zależnych od serwera nie są przenośne.

getAttributeNames()

public abstract Enumeration getAttributeNames()

Zwraca nazwy wszystkich atrybutów obecnego kontekstu jako Enumeration obiektów String. Zwraca pustą Enumeration, jeżeli kontekst nie posiada atrybutów. Metoda została wprowadzona w Servlet API 2.1.

getContext()

public abstract ServletContext getContext(String sciezkauri)

Zwraca egzemplarz ServletContext przypisany do danej ścieżki URI. Dana ścieżka musi być bezwzględna (musi rozpoczynać się od /) i jest interpretowana w oparciu o katalog macierzysty serwera. Metoda ta zapewnia serwletowi dostęp do kontekstu innego niż własny, umożliwiając przeglądanie danych wewnątrz tego kontekstu lub otrzymanie RequestDispatcher do zasobów wewnątrz tego kontekstu. W środowisku zabezpieczonym lub rozproszonym kontener serwletów może zwrócić null dla dowolnej ścieżki. Metoda została wprowadzona w Servlet API 2.1.

getInitParameter()

public abstract String getInitParameter(String nazwa)

Zwraca wartość danego parametru inicjacji lub null, jeżeli nie odnajdzie pasującego parametru. Metoda ta może udostępnić przydatne informacje o konfiguracji całej aplikacji WWW. Na przykład, może udostępnić adres poczty elektronicznej administratora systemu lub nazwę systemu przechowującego dane krytyczne. Parametry inicjacji kontekstu są przydzielane w deskryptorze aplikacji WWW. Metoda została wprowadzona w Servlet API 2.2.

getInitParameterNames()

public abstract Enumeration getInitParameterNames()

Zwraca nazwy wszystkich parametrów inicjacji danego kontekstu jako Enumeration obiektu String. Zwraca ona pustą Enumeration, jeżeli kontekst nie posiada żadnych atrybutów. Parametry inicjacji kontekstu są przydzielane w deskryptorze aplikacji WWW. Metoda została wprowadzona w Servlet API 2.2.

getMajorVersion()

public abstract int getMajorVersion()

Zwraca numer głównej wersji Servlet API obsługiwanego przez kontener serwletów. Na przykład, kontener implementujący wersję 2.1 zwróci 2. Metoda została wprowadzona w Servlet API 2.1.

getMimeType()

public abstract String getMimeType(string plik)

Zwraca typ MIME danego pliku lub null, jeżeli jest on nieznany. Niektóre implementacje zwracają text/plain jeżeli plik nie istnieje. Popularne typy MIME to text/html, text/plain, image/gif i image/jpeg.

getMinorVersion()

public abstract int getMinorVersion()

Zwraca numer pobocznej wersji Servlet API obsługiwanego przez kontener serwletów. Na przykład, kontener implementujący wersję 2.1 zwróci 1. Metoda została wprowadzona w Servlet API 2.1.

getNamedDispatcher()

public abstract RequestDispatcher getNamedDispatcher(String nazwa)

Zwraca RequestDispatcher, który odsyła działanie do zasobu według nazwy, zamiast według ścieżki. Pozwala to na rozsyłanie do zasobów, które niekoniecznie są dostępne publicznie. Serwlety (oraz strony JSP) mogą otrzymać nazwy poprzez administrację serwera lub przez deskryptor aplikacji WWW. Metoda zwraca null, jeżeli, niezależnie od powodu, kontekst nie może zwrócić rozesłania. Metoda została wprowadzona w Servlet API 2.2.

getRealPath()

public abstract String get RealPath(String sciezka)

Zwraca prawdziwą ścieżkę systemu plików danej „ścieżki wirtualnej” lub null, jeżeli tłumaczenie nie mogło zostać przeprowadzone (na przykład kiedy plik znajduje się w zdalnym systemie plików lub jest dostępny jedynie wewnątrz archiwum .war). Jeżeli dana ścieżka wynosi /, metoda zwraca katalog macierzysty dokumentów kontekstu. Jeżeli dana ścieżka jest taka sama, jak zwrócona przez getPathInfo(), metoda zwraca tę samą realną ścieżkę, jaką zwróciłaby przy wywołaniu getPathTranslated(). Nie istnieje odpowiednik CGI.

getResource()

public abstract URL getResource(String sciezka)

Zwraca URL zasobu odwzorowanego w podanej ścieżce. Ścieżka musi rozpoczynać się od /, i jest interpretowana jako względna do katalogu macierzystego kontekstu. Metoda może zwrócić null, jeżeli skojarzenie jakiegokolwiek URL-a ze ścieżką nie będzie możliwe. Metoda ta umożliwia kontenerowi udostępnienie zasobów serwletom z dowolnego źródła. Zasoby mogą zostać odnalezione lokalnie, w zdalnym systemie plików, bazie danych lub pliku .war. Niektóre kontenery mogą również umożliwiać zapis w obiekcie URL przy pomocy metod klasy URL. Metoda ta powinna zostać zastosowana kiedy nie wszystkie zasoby to pliki lokalne — tak jest w przypadku środowiska rozproszonego (w którym kontener serwletów może znajdować się na innym komputerze niż zasoby) lub kiedy zawartość pochodzi z pliku .war (którego pliki nie są dostępne bezpośrednio). Zawartość zasobów zwracana jest w formie surowej, tak więc należy pamiętać, że żądanie strony .jsp zwróci kod źródłowy JSP w celu dołączenia zasobów uruchomieniowych JSP należy zamiennie zastosować RequestDispatcher. Metoda ta posiada inny cel niż Class.getResource(), która wyszukuje w oparciu o mechanizm ładowania klas. Metoda ta nie wykorzystuje mechanizmów ładowania klas. Została ona wprowadzona w Servlet API 2.1.

getResourceAsStream()

public abstract InputStream getResourceAsStream(String sciezka)

Zwraca InputStream w celu odczytania zawartości zasobu odwzorowanego według konkretnej ścieżki. Ścieżka musi rozpoczynać się / i jest interpretowana według katalogu macierzystego kontekstu. Metoda może zwracać null, jeżeli ze ścieżką nie można było połączyć żadnego zasobu. Wykorzystanie tej metody jest często łatwiejsze niż getResource(); jednak podczas wykorzystywania tej metody tracone są metainformacje na temat zasobów, takie jak wielkość i typ jej zawartości, dostępne przy pomocy getResource(). Metoda została wprowadzona w Servlet API 2.1.

getServerInfo()

public abstract String getServerInfo()

Zwraca nawę i numer wersji oprogramowania serwera, rozdzielone ukośnikiem (/). Wartość jest równa wartości zmiennej CGI SERVER_SOFTWARE.

getServlet()

public abstract Servlet getServlet(String nazwa) throws ServletException;

Zwraca null w Servlet API 2.1 i późniejszych. Poprzednio zwracała pobrany serwlet pasujący do podanej nazwy i URL-u lub null, jeżeli serwlet nie mógł zostać odnaleziony. W API 2.1 metoda została opuszczona i zdefiniowana tak, by zwracała null, ponieważ bezpośredni dostęp do innego egzemplarza serwletu otwiera zbyt wiele możliwości dla błędu. Dzieje się tak dlatego, że serwlety mogą zostać zniszczone przez kontener w dowolnym czasie, tak więc żaden obiekt oprócz kontenera nie powinien posiadać bezpośredniego odwołania do serwletu. Poza tym, w przypadku serwera obsługującego dystrybucję ładunku, w którym serwlety rozkładane są na kilku różnych serwerach, niemożliwe może okazać się zwrócenie lokalnego odwołania do serwletu. Zamiast tego serwlety powinny współpracować poprzez wykorzystanie współdzielonych atrybutów ServletContext. Technicznie rzecz biorąc, zdefiniowanie metody tak, by zawsze zwracała null, nie usuwa wstecznej kompatybilności, ponieważ serwer zawsze miał możliwość zwracania null w tej metodzie.

getServletNames()

public abstract Enumeration getServletNames();

Zwraca pustą Enumeration w Servlet API 2.1 i późniejszych. Poprzednio zwracała Enumeration zawierającą nazwy obiektów serwletów załadowanych do danego kontekstu. Metoda ta została opuszczona i zdefiniowana do zwracania pustej Enumeration w Servlet API 2.1 z tych samych powodów, dla których getServlet() została opuszczona i zdefiniowana tak, by zwracała. Metoda ta została wprowadzona w Servlet API 2.0.

getServlets()

public abstract Enumeration getServlets();

Zwraca pustą Enumeration w Servlet API 2.1 i późniejszych. Poprzednio zwracała Enumeration zawierającą obiekty Servlet załadowane do danego kontekstu. Metoda ta została opuszczona w Servlet API 2.0 na rzecz getServletNames(). Została zdefiniowana do zwracania pustej Enumeration w Servlet API 2.1 według zachowania metody getServletNames().

log()

public abstract void log(String wiad);

Zapisuje daną wiadomość w dzienniku serwletu. Miejsce zapisu jest zależne od serwera, zazwyczaj jest to plik dziennika zdarzeń.

public abstract void log(string wiad, Throwable t);

Zapisuje daną wiadomość i ścieżkę stosu obiektu Throwable w dzienniku serwletu. Miejsce zapisu jest zależne od serwera, zazwyczaj jest to plik dziennika zdarzeń. Metoda została wprowadzona w Servlet API 2.1.

public abstract void log(Exception wyjatek, String wiad);

Zapisuje daną wiadomość i ścieżkę wyjątku Exception w dzienniku serwletu. Miejsce zapisu jest zależne od serwera. Proszę zauważyć niestandardowe umieszczenie parametru Exception na pozycji pierwszej, a nie ostatniej. Metoda ta została opuszczona w Servlet API 2.1 na rzecz metody log(String wiad, Throwable t), w której zastosowano standardowy porządek elementów i która pozwala na zapisanie każdego obiektu Trowable, nie tylko Exception. Metoda została wprowadzona w Servlet API 2.0.

removeAttribute()

public abstract void removeAttribute(String nazwa);

Usuwa z kontekstu atrybut o danej nazwie. Atrybuty powinny zostać usunięte, kiedy nie są już dłużej potrzebne, w celu odblokowania miejsca zajmowanego przez nie w pamięci. Metoda została wprowadzona w Servlet API 2.1.

setAttribute()

public abstract void setAttribute(String nazwa, Object o);

Dowiązuje obiekt o danej nazwie do kontekstu serwletu. Każde istniejące dowiązanie o tej samej nazwie zostaje zastąpione. Metoda została wprowadzona w Servlet API 2.1.

ServletException

Zestawienie

Nazwa klasy	javax.servlet.ServletException
Superklasa	java.lang.exception
Bezpośrednie podklasy	javax.servlet.UnavailableException
Implementowane interfejsy	Brak
Dostępność	Servlet API 1.0 i późniejsze

Opis

Ogólny wyjątek zgłaszany przez serwlety napotykające trudności.

Podsumowanie klasy

public class ServletException extends java.lang.Exception {

// Konstruktory

public ServletException(); // Nowość w 2.0

public ServletException(String wiad);

public ServletException(String wiad, Throwable podstPrzycz); // Nowość w 2.1

public ServletException(Throwable podstPrzycz); // Nowość w 2.1

public Throwable getRootCause(); // Nowość w 2.1

}

Konstruktory

public ServletException()

public ServletException();

public ServletException(String wiad);

public ServletException(String wiad, Throwable podstPrzycz);

public ServletException(Throwable podstPrzycz);

Konstruuje nowy wyjątek ServletException, z opcjonalną opisową wiadomością i opcjonalną „podstawową przyczyną” wyjątku. Jeżeli wiadomość została określona, może być ona odczytana przy pomocy wywołania getMessage(); jeżeli określona została podstawowa przyczyna, może ona być odczytana przy pomocy wywołania getRootCause(). Wiadomości i podstawowe przyczyny są zazwyczaj dołączane do dzienników serwera i komunikatów o błędach dla użytkowników. Wersje konstruktora pobierające podstawową przyczynę zostały wprowadzone w Servlet API 2.1.

Metody egzemplarzy

getRootCause()

public Throwable getRootCause();

Zwraca obiekt Throwable, który spowodował wyjątek serwletu lub null, jeżeli nie istnieje podstawowa przyczyna. Metoda została wprowadzona w Servlet API 2.1.

ServletInputStream

Zestawienie

Nazwa klasy	javax.servlet.ServletInputStream
Superklasa	java.io.InputStream
Bezpośrednie podklasy	Brak
Implementowane interfejsy	Brak
Dostępność	Servlet API 1.0 i późniejsze

Opis

Dostarcza potoku wyjściowego służącego do odczytywania danych binarnych z żądania klienta oraz metody readLine() służącej do odczytywania danych linia po linii. ServletInputStream jest zwracany przez metodę getInputStream() ServletRequest. W przypadku serwletów HTTP ServletInputStream umożliwia dostęp do wysłanych danych POST.

Podsumowanie klasy

public abstract class ServletInputStream extends java.io.InputStream {

// Konstruktory

protected ServletInputStream();

// Metody egzemplarzy

public int readLine(byte b[], int off, int dlug) throws IOException;

}

Konstruktory

ServletInputStream()

protected ServletInputStream();

Domyślny konstruktor nie wykonuje żadnych działań. Serwlet nie powinien nigdy konstruować swojego własnego ServletInputStream.

Metody egzemplarzy

readLine()

public int readLine(byte b[], int off, int dlug) throws IOException;

Odczytuje bajty z potoku wejściowego do tablicy bajtów b, rozpoczynając od offsetu w tablicy podanego w off. Zatrzymuje odczytywanie po napotkaniu znaku \n lub po odczytaniu ilości dlug bajtów. Kończący znak \n jest również odczytywany do bufora. Zwraca ilość odczytanych bajtów lub -1, jeżeli osiągnięto koniec potoku. Wersja tej klasy dołączona do Servlet API 2.0 zawierała błąd, który powodował ignorowanie parametru dlug, co dawało wynik w zgłaszaniu wyjątku ArrayIndexOutOfBoundsException podczas odczytywania linii dłuższej niż bufor. Błąd ten został naprawiony w Servlet API 2.1.

ServletOutputStream

Zestawienie

Nazwa klasy	javax.servlet.ServletOutputStream
Superklasa	java.io.OutputStream
Bezpośrednie podklasy	Brak
Implementowane interfejsy	Brak
Dostępność	Servlet API 1.0 i późniejsze

Opis

Dostarcza strumienia wyjściowego służącego do wysyłania danych binarnych z powrotem do klienta. Serwlet uzyskuje obiekt ServletOutputStream poprzez metodę getOutpuStream() ServletResponse. Chociaż zawiera różnorodne metody println() służące do wysyłania tekstu lub HTML, ServletOutputStream został przewyższony przez PrintWriter. Powinien być wykorzystywany jedynie do wysyłania danych binarnych. Jeżeli tworzy się podklasę ServletOutputStream, należy dostarczyć implementacji metody write(int).

Podsumowanie klasy

public abstract class ServletOutputStream extends java.io.OutputStream {

// Konstruktory

protected ServletOutputStream();

// Metody egzemplarzy

public void print(boolean b) throws IOException;

public void print(char c) throws IOException;

public void print(double d) throws IOException;

public void print(float f) throws IOException;

public void print(int i) throws IOException;

public void print(long l) throws IOException;

public void print(String s) throws IOException;

public void println() throws IOException;

public void println(boolean b) throws IOException;

public void println(char c) throws IOException;

public void println(double d) throws IOException;

public void println(float f) throws IOException;

public void println(int i) throws IOException;

public void println(long l) throws IOException;

public void println(String s) throws IOException;

}

Konstruktory

ServletOutputStream()

protected ServletOutputStream();

Domyślny konstruktor nie wykonuje żadnych działań.

Metody egzemplarzy

print()

public void print(boolean b) throws IOException;

public void print(char c) throws IOException;

public void print(double d) throws IOException;

public void print(float f) throws IOException;

public void print(int i) throws IOException;

public void print(long l) throws IOException;

public void print(String s) throws IOException;

Wyświetla klientowi dane informacje, bez kończącego znaku powrotu karetki/końca linii (carriage return/line feed —CRLF).

println()

public void println() throws IOException;

public void println(boolean b) throws IOException;

public void println(char c) throws IOException;

public void println(double d) throws IOException;

public void println(float f) throws IOException;

public void println(int i) throws IOException;

public void println(long l) throws IOException;

public void println(String s) throws IOException;

Wyświetla klientowi dane informacje, z kończącym CRLF. Metoda bez żadnych parametrów wyświetla po prostu CRLF.

ServletRequest

Zestawienie

Nazwa interfejsu	javax.servlet.ServletRequest
Superinterfejs	Brak
Bezpośrednie podinterfejsy	javax.servlet.http.HttpServletRequest
Implementowany przez	Brak
Dostępność	Servlet API 1.0 i późniejsze

Opis

Obiekt ServletRequest zawiera w sobie wszystkie informacje na temat żądania klienta, włączając w to parametry żądania, atrybut żądania, lokalizacje klienta oraz potok wejściowy służący do odczytywania danych binarnych z głównej części żądania. Możliwe jest utworzenie podklasy ServletRequest w celu dostarczenia dodatkowych informacji zależnych od protokołu. Na przykład HttpServletRequest zawiera metody służące do manipulowania nagłówkami HTTP.

Deklaracja interfejsu

public interface ServletRequest {

// Metody

public abstract Object getAttribute(String nazwa);

public abstract Enumeration getAttributeNames(String nazwa); // Nowość w 2.1

public abstract String getCharacterEncoding(); // Nowość w 2.0

public abstract int getContentLength()

public abstract String getContentType();

public abstract ServletInputStream getInputStream() throws IOException;

public abstract Locale getLocale(); // Nowość w 2.2

public abstract Enumeration getLocales(); // Nowość w 2.2

public abstract String getParameter(String nazwa);

public abstract Enumeration getParameterNames();

public abstract String[] getParameterValues(String nazwa);

public abstract String getProtocol();

public abstract BufferedReader getReader() throws IOException // Nowość w 2.0

public abstract String getRealPath(String sciezka); // Opuszczona

public abstract String getRemoteAddr();

public abstract String getRemoteHost();

public abstract RequestDispatcher getRequestDispatcher(String sciezka) // Nowość w 2.1

public abstract String getScheme();

public abstract String getServerName();

public abstract int getServerPort();

public abstract boolean isSecure(); // Nowość w 2.2

public abstract void removeAttribute(String nazwa); // Nowość w 2.2

public abstract void setAttribute(String nazwa, Object o); // Nowość w 2.1

}

Metody

getAttribute()

public abstract Object getAttribute(String nazwa)

Zwraca wartość danego atrybutu żądania jako Object lub null, jeżeli atrybut nie istnieje. Atrybuty żądania zależne od serwera mogą być ustawiane automatycznie przez kontener serwletów w celu dostarczenia serwletom informacji wykraczających poza zasięg tych dostarczanych przez podstawowy Servlet API. Atrybuty mogą również zostać automatycznie ustawione przez serwlety, co jest sposobem przekazywania informacji pomiędzy serwletami podczas wykorzystywania RequestDispatcher. Nazwy atrybutów powinny być zgodne z tą samą konwencją, co nazwy pakietów. Nazwy pakietów java.* i sun.* są zarezerwowane przez dział Java Software firmy Sun Microsystems (dawniej znany jako JavaSoft), a com.sun.* jest zarezerwowany dla użytku firmy Sun Microsystems. Proszę przejrzeć dokumentację serwera w celu obejrzenia listy wbudowanych atrybutów. Proszę pamiętać, że serwlety oparte na atrybutach zależnych od serwera nie są przenośne.

getAttributeNames()

public abstract Enumeration getAttributeNames()

Zwraca nazwy wszystkich atrybutów obecnego kontekstu jako Enumeration obiektów String. Zwraca pustą Enumeration, jeżeli kontekst nie posiada atrybutów. Metoda została wprowadzona w Servlet API 2.1.

getCharacterEncoding()

public abstract String getCharacterEncoding()

Zwraca kodowanie potoku wejściowego serwletu lub null, jeżeli nie jest on znany. Metoda został wprowadzona w Servlet API 2.0.

getContentLength()

public abstract int getContentLength()

Zwraca długość w bajtach zawartości przesyłanej przez potok wejściowy lub -1, jeżeli długość nie jest znana (na przykład podczas braku danych). Równoważna ze zmienną CGI CONTENT_LENGTH.

getContentType()

public abstract String getContentType()

Zwraca typ zawartości przesyłanej poprzez potok wejściowy lub null, jeżeli typ nie jest znany lub nie występują żadne dane. Równoważna ze zmienną CGI CONTENT_TYPE.

getInputStream()

public abstract ServletInputStream getInputStream()

throws IOException, IllegalStateException

Pobiera potok wejściowy jako obiekt ServletInputStream. ServletInputStream jest bezpośrednią podklasą InputStream, i obiekt może być traktowany w identyczny sposób jak zwykły obiekt InputStream, z dodatkową możliwością efektywnego odczytywania wpisanych danych linia po linii do tablicy bajtów. Metoda ta powinna być wykorzystywana do odczytywania wpisów binarnych. Zgłasza ona wyjątek IllegalStateException, jeżeli wcześniej w żądaniu wywołana została metoda getReader(). IllegalStateException nie musi być otwarcie przechwytywany.

getLocale()

public abstract Locale getLocale()

Zwraca lokalizację Locale preferowaną przez klienta, odczytaną z nagłówka żądania klienta Accept_Language. Jeżeli żądanie klienta nie posiada nagłówka Accept_Language, metoda zwraca domyślną lokalizację serwera. W celu wykonania dokładniejszego poszukiwania lokalizacji należy wykorzystać klasę com.oreilly.servlet.LocaleNegotiator. Metoda została wprowadzona w Servlet API 2.2.

getLocales()

public abstract Enumeration getLocales()

Zwraca Enumeration obiektów Locale wskazujących na lokalizacje akceptowane przez klienta, na podstawie nagłówka Accept-Language, od najbardziej do najmniej preferowanej. Jeżeli żądania klienta nie zawiera nagłówka Accept_Language, metoda zwraca Enumeration zawierającą jeden Locale, domyślną lokalizację serwera. W celu wykonania dokładniejszego poszukiwania lokalizacji należy wykorzystać klasę com.oreilly.servlet.LocaleNegotiator. Metoda została wprowadzona w Servlet API 2.2.

getParameter()

public abstract String getParameter(String nazwa)

Zwraca wartość danego parametru jako łańcuch String. Zwraca null, jeżeli parametr nie istnieje, lub pusty łańcuch, jeżeli parametr istnieje, ale nie posiada żadnej wartości. Wartość jest zawsze zwracana w swojej zwykłej, zdekodowanej formie. Jeżeli parametr posiada kilka wartości, należy wykorzystać metodę getParameterValues(), która zwraca tablicę wartości. Jeżeli metoda jest wywoływana na parametrze posiadającym kilka wartości, zwracana wartość jest równa pierwszemu elementowi tablicy zwracanej przez getParameterValues(). Jeżeli informacje na temat parametrów nadeszły w formie zakodowanych danych POST, mogą być one niedostępne, jeżeli dane POST zostały wcześniej ręcznie odczytane przy pomocy metody getReader() lub getInputStream(). Metoda ta była przez pewien czas opuszczona na rzecz getParameterValues(), ale dzięki powszechnym protestom środowiska programistów, została przywrócona w Servlet API 2.0.

getParameterNames()

public abstract Enumeration getParameterNames()

Zwraca nazwy wszystkich parametrów jako Enumeration obiektów String. Zwraca pustą Enumeration, jeżeli serwlet nie posiada żadnych parametrów.

getParameterValues()

public abstract String[] getParameterValues(String nazwa)

Zwraca wszystkie wartości danego parametru jako tablicę obiektów String lub null, jeżeli dany parametr nie istnieje. Pojedyncza wartość jest zwracana jako tablica o długości 1.

getProtocol()

public abstract String getProtocol()

Zwraca nazwę i wersję protokołu wykorzystywanego przez żądanie jako String o wzorze protokol/wersja-glowna.wersja-poboczna. Równoważna ze zmienną CGI SERVER_PROTOCOL.

getReader()

public abstract BufferedReader getReader()

throws IOException, IllegalStateExeption

Metoda ta odczytuje potok wejściowy jako obiekt BufferedReader, który powinien zostać wykorzystany do odczytania wprowadzonych danych opartych na znakach, ponieważ mechanizm odczytujący odpowiednio tłumaczy kodowania. Metoda zgłasza IllegalStateException, jeżeli na tym samym żądaniu poprzednio wywołano getInputStream(). Zgłasza UnsupportedEncodingException, jeżeli kodowanie wykorzystywane we wprowadzonych danych nie jest obsługiwane lub znane. Metoda została wprowadzona w Servlet API 2.0.

getRealPath()

public abstract String getRealPath(String sciezka)

Zwraca bezwzględną ścieżkę systemu plików każdej danej „ścieżki wirtualnej” lub null, jeżeli tłumaczenie nie mogło zostać przeprowadzone. Jeżeli dana ścieżka wynosi /, zwraca macierzysty katalog dokumentów serwera. Jeżeli dana ścieżka jest taka sama, jak zwracana przez getPathInfo(), zwraca tę samą ścieżkę, jak byłaby zwrócona przez getPathTraslated(). Dla tej metody nie istnieje równoważnik CGI. Metoda została opuszczona w Servlet API 2.1 na rzecz metody getRealPath() w ServletContext.

getRemoteAddr()

public abstract String getRemoteAddr()

Zwraca adres IP komputera klienta jako String. Informacja ta jest odczytywana z portu łączącego serwer z klientem, tak więc adres zdalny może być adresem serwera proxy. Równoważna zmiennej CGI REMOTE_ADDR.

getRemoteHost()

public abstract String getRemoteHost()

Zwraca nazwę komputera klienta. Informacja ta jest odczytywana z portu łączącego serwer z klientem, tak więc nazwa może być nazwą serwera proxy. Równoważna zmiennej CGI REMOTE_HOST.

getRequestDispatcher()

public abstract RequestDispatcher getRequestDispatcher(String sciezka)

Zwraca RequestDispatcher posiadający możliwość przekierowywania żądania do danej ścieżki. RequestDispatcher może być wykorzystany do przekierowania żądania do zasobu lub do dołączenia zawartość tego zasobu do aktualnej odpowiedzi. Zasób może być dynamiczny lub statyczny. Określona ścieżka może być względna, chociaż nie może wykraczać poza aktualny kontekst serwletów. Jeżeli ścieżka rozpoczyna się od /, jest interpretowana jako względna do aktualnego macierzystego katalogu dokumentów. Metoda zwraca null, jeżeli kontener serwletów nie może zwrócić RequestDispatcher, niezależnie od powodu. Różnica pomiędzy tą metodą i getRequestDispatcher() w ServletContext jest taka, że ta metoda może pobierać ścieżkę względną. Metoda została wprowadzona w Servlet API 2.2.

getScheme()

public abstract String getScheme()

Metoda zwraca schemat wykorzystany do wykonania tego żądania. Może być to na przykład http, https i ftp, jak również jeden z nowszych właściwych Javie schematów takich jak jdbc i rmi.

GetServerName()

public abstract String getServerName()

Zwraca nazwę serwera, który otrzymał żądanie. Jest to atrybut ServletRequest, ponieważ może się zmieniać dla różnych żądań, co jest związane z różnymi typami zależności klienta od serwera. Podobna do zmiennej CGI SERVER_NAME.

GetServerPort()

public abstract int getServerPort()

Zwraca numer portu, który otrzymał żądanie, Równoważna zmiennej CGI SERVER_PORT.

isSecure()

public abstract boolean isSecure()

Zwraca odpowiedź, czy żądanie zostało wykonane przy pomocy bezpiecznego kanału, takiego jak HTTPS. Metoda została wprowadzona w Servlet API 2.2.

removeAtrribute()

public abstract void removeAttribute(String nazwa)

Usuwa z żądania atrybut o danej nazwie. Atrybuty zależne od serwera generalnie nie mogą zostać usunięte. Metoda została wprowadzona w Servlet API 2.2.

setAtrribute()

public abstract void setAttribute(String nazwa, Object o)

Dowiązuje do aktualnego żądania obiekt o danej nazwie. Wszystkie istniejące dowiązania o tej samej nazwie zostają usunięte. Atrybuty żądania są najczęściej ustawiane jako sposób przekazywania informacji pomiędzy serwletami wykorzystującymi RequestDispatcher. Nazwy atrybutów powinny być zgodne z tą samą konwencją, co nazwy pakietów. Nazwy pakietów java.* i sun.* są zarezerwowane przez dział Java Software firmy Sun Microsystems (dawniej znany jako JavaSoft), a com.sun.* jest zarezerwowany dla użytku firmy Sun Microsystems. Metoda została wprowadzona w Servlet API 2.2.

ServletResponse

Zestawienie

Nazwa interfejsu	javax.servlet.ServletResponse
Superinterfejs	Brak
Bezpośrednie podinterfejsy	javax.servlet.http.HttpServletResponse
Implementowany przez	Brak
Dostępność	Servlet API 1.0 i późniejsze

Opis

Serwlety wykorzystują obiekty ServletResponse do wysyłania zakodowanych w MIME danych z powrotem do klienta. Aby wysłać dane binarne, należy wykorzystać ServletOutputStream zwrócony przez getOutputStream(). W celu wysłania danych zawierających znaki należy wykorzystać PrintWriter zwrócony przez getWriter(). Można otwarcie ustawić typ MIME wyświetlanych danych przy pomocy metody setContentType(), a lokalizację odpowiedzi przy pomocy setLocale(). Należy wykonać te wywołania przed wywołaniem getWriter(), ponieważ metoda getWriter() sprawdza typ zawartości i lokalizację w celu określenia kodowania, które należy wykorzystać. Więcej informacji na temat MIME jest dostępnych w dokumencie RFC 2045 pod adresem http://www.ietf.org/rfc/rfc2045.txt.

Deklaracja interfejsu

public interface ServletResponse {

// Metody

public abstract void flushBuffer() throws IOException; // Nowość w 2.2

public abstract int getBufferSize(); // Nowość w 2.2

public abstract String getCharacterEncoding(); // Nowość w 2.0

public abstract Locale getLocale(); // Nowość w 2.2

public abstract ServletOutputStream getOutputStream()

throws IOException, IllegalStateException;

public abstract PrintWriter getWriter() // Nowość w 2.0

throws IOException, IllegalStateException;

public abstract boolean isCommitted(); // Nowość w 2.2

public abstract void reset() throws IllegalStateException; // Nowość w 2.2

public abstract void setBufferSize(int wielkosc) // Nowość w 2.2

throws IllegalStateException;

public abstract void setContentLength(int dlug);

public abstract void setContentType(String typ);

public abstract void setLocale(Locale lok); // Nowość w 2.2

}

Metody

FlushBuffer()

public abstract void flushBuffer() throws IOException;

Wymusza wyświetlenie klientowi wszystkich danych znajdujących się w buforze. Wywołanie tej metody automatycznie zatwierdza odpowiedź, co oznacza, że kod stanu oraz nagłówki zostaną zapisane, a metoda reset() nie będzie już dostępna. Metoda została wprowadzona w Servlet API 2.2.

getBufferSize()

public abstract int getBufferSize();

Zwraca liczbę int informującą o wielkości aktualnego bufora lub 0 w rzadkim przypadku, kiedy buforowanie nie jest wykorzystywane. Metoda została wprowadzona w Servlet API 2.2.

GetCharacterEncoding()

public abstract String getCharacterEncoding()

Zwraca kodowanie wykorzystywane w aktualnej części głównej MIME. Jest to kodowanie określone przez przydzielony typ zawartości, lub ISO-8859-1, jeżeli nie określono żadnego kodowania. Metoda została wprowadzona w Servlet API 2.0.

getLocale()

public abstract Locale getLocale()

Zwraca lokalizację Locale aktualnie przypisaną do odpowiedzi. Metoda została wprowadzona w Servlet API 2.2.

GetOutputStream()

public abstract ServletOutputStream getOutputStream()

throws IOException, IllegalStateException;

Zwraca ServletOutputStream służący do zapisywania binarnych (bit-po-bicie) danych odpowiedzi. Nie jest wykonywane żadne kodowanie. Zgłasza IllegalStateException, jeżeli na aktualnej odpowiedzi wywołano wcześniej getWriter().

getWriter()

public abstract PrintWriter getWriter()

throws IOException, IllegalStateException;

Zwraca PrintWriter służący do zapisywania opartych na znakach danych odpowiedzi. Mechanizm wyświetlający koduje znaki zależnie od jakiegokolwiek kodowania podanego w typie zawartości. Jeżeli w typie zawartości nie określono żadnego kodowania, jak to się zdarza najczęściej, mechanizm wykorzystuje kodowanie ISO-8859-1 (Latin-1), odpowiednie dla języków zachodnioeuropejskich. Zgłasza IllegalStateException, jeżeli na aktualnej odpowiedzi wywołano wcześniej getOutputStream(), a UnsupportedEncodingException, jeżeli kodowanie potoku wyjściowego nie jest obsługiwane lub znane. Metoda została wprowadzona w Servlet API 2.2.

isCommitted()

public abstract boolean isCommitted()

Zwraca wartość boolean wskazującą, czy jakakolwiek część odpowiedzi została już wysłana. Jeżeli metoda zwróci true, jest już za późno, by zmienić kody stanu i nagłówki. Metoda została wprowadzona w Servlet API 2.2.

reset()

public abstract void reset() throws IllegalStateException;

Czyści bufor odpowiedzi, a także aktualnie przypisany kod stanu i nagłówki odpowiedzi. Metoda ta musi zostać wywołana przed zatwierdzeniem odpowiedzi, inaczej zgłasza IllegalStateException. reset() jest automatycznie wywoływana przez metody sendError() i sendRedirect(). Metoda została wprowadzona w Servlet API 2.2.

setBufferSize()

public abstract void setBufferSize(int wielkosc) throws IllegalStateException;

Przekazuje serwerowi minimalną wielkość (w bajtach) bufora odpowiedzi, którą zaakceptuje serwlet. Serwer może dostarczyć większego bufora niż ten, którego zażądano — na przykład w celu utrzymania buforów jako bloków o wielkości 8Kb w celu ułatwienia ich ponownego wykorzystania. Większy bufor pozwala na zapisanie dłuższej zawartości przez jej właściwym wysłaniem, a w związku z tym daje serwletowi więcej czasu na ustawienie odpowiednich kodów stanu i nagłówków. Mniejszy bufor zmniejsza obciążenie pamięci serwera i pozwala na szybsze otrzymywanie danych przez klienta. Metoda ta musi zostać wywołana przed zapisaniem dowolnej zawartości w głównej części odpowiedzi; jeżeli zawartość została zapisana, metoda zgłasza wyjątek IllegalStateException. Metoda została wprowadzona w Servlet API 2.2.

setContentLength()

public abstract void setContentLength(int dlug)

Ustawia długość zawartości zwracanej przez serwer. W przypadku serwletów HTTP, ustawia nagłówek HTTP Content-Length. Serwlety HTTP wykorzystuję tę metodę w celu umożliwienia trwałych połączeń i wspomożenia monitorów postępu klienta. Jej wykorzystanie jest opcjonalne. Jeżeli zawartość odpowiedzi mieści się całkowicie w wielkości przydzielonego bufora odpowiedzi, serwer może automatycznie ustawić długość zawartości.

setContentType()

public abstract void setContentType(String typ)

Metoda ustawia typ zawartości odpowiedzi na typ określony. W przypadku serwletów HTTP, ustawia nagłówek HTTP Content-Type.

setLocale()

public abstract void setLocale(Locale lok)

Ustawia lokalizację odpowiedzi. Serwer modyfikuje nagłówki Content-Language i Content-Type odpowiednio do danej lokalizacji. Metoda powinna zostać wywołana po ustawieniu Content-Type, a przed wywołaniem getWriter(). Domyślnie lokalizacja odpowiedzi jest równa domyślnej lokalizacji serwera. Metoda została wprowadzona w Servlet API 2.2.

SingleThreadModel

Zestawienie

Nazwa interfejsu	javax.servlet.SingleThreadModel
Superinterfejs	Brak
Bezpośrednie podinterfejsy	Brak
Implementowany przez	Brak
Dostępność	Servlet API 2.0 i późniejsze

Opis

SingleThreadModel jest interfejsem znaczników nie posiadającym metod. Jeżeli serwlet implementuje ten interfejs, kontener serwletów upewnia się, że każdy egzemplarz serwletu obsługuje jedynie jedno żądanie usługi w jednym czasie. Na przykład, kontener serwletów może zaimplementować tę funkcjonalność poprzez utrzymywanie puli egzemplarzy serwletów i przekierowywanie przychodzących żądań do wolnych serwletów w puli. Wykorzystanie SingleThreadModel zabezpiecza sam serwlet przed wątków; jednak wykorzystanie tego interfejsu nie przeciwdziała problemom z synchronizacją, które są powodowane przez serwlety uzyskujące dostęp do współdzielonych zasobów takich jak statyczne zmienne klas lub zmienne zdalne dla serwletu. Interfejs ten jest przydatny w bardzo niewielkiej ilości sytuacji.

Deklaracja interfejsu

public interface SingleThreadModel {

}

UnavailableException

Zestawienie

Nazwa klasy	javax.servlet.UnavailableException
Superklasa	java.io.ServletException
Bezpośrednie podklasy	Brak
Implementowane interfejsy	Brak
Dostępność	Servlet API 1.0 i późniejsze

Opis

Serwlet może zgłosić wyjątek UnavailableException w dowolnym czasie w celu wskazania, że nie jest dostępny w celu zaspokajania żądań klientów. Istnieją dwa typy niedostępności — stała (w której problem nie może sam się rozwiązać i musi zostać podjęta akcja administracyjna) i tymczasowa (w której problem najprawdopodobniej sam się rozwiąże po pewnym czasie). Aby oznaczyć serwlet jako czasowo niedostępny należy podczas konstruowania wyjątku określić czas (w sekundach). Dobrze napisane kontenery serwletów wykorzystają określony czas w celu utworzenia lepszych komunikatów o błędach dla klienta. Implementacje serwletów mogą traktować niedostępność tymczasową jako niedostępność stałą.

Podsumowanie klasy

public class UnavailableException extends ServletException {

// Konstruktory

public UnavailableException(int sekundy, Servlet serwlet, String wiad); // Opuszczona

public UnavailableException(Servlet serwlet, String wiad); // Opuszczona

public UnavailableException(String wiad); // Nowość w 2.2

public UnavailableException(String wiad, int sekundy); // Nowość w 2.2

// Metody egzemplarzy

public Servlet getServlet(); // Opuszczona

public int getUnavailableSeconds();

public boolean isPermanent();

}

Konstruktory

UnavailableException()

public UnavailableException(String wiad)

public UnavailableException(String wiad, int sekundy)

public UnavailableException(Servlet serwlet, String wiad)

public UnavailableException(int sekundy, Servlet serwlet, String wiad)

Konstruuje wyjątek UnavailbleException z daną wyjaśniającą wiadomością. Okres niedostępności może zostać opcjonalnie określony (w sekundach). Dwa konstruktory z podpisami, które przyjmują parametr Servlet zostały opuszczone w Servlet API 2.2 na rzecz prostszych i bezpieczniejszych wersji konstruktora nie przyjmujących egzemplarza serwletu.

Metody egzemplarzy

getServlet()

public Servlet getServlet()

Zwraca serwlet, który zgłosił aktualny wyjątek lub null, jeżeli egzemplarz serwletu nie został dostarczony konstruktorowi. Metoda została opuszczona w Servlet API 2.2 ze względów bezpieczeństwa.

getUnavailableSeconds()

public int getUnavailableSeconds()

Zwraca ilość sekund, przez które serwlet będzie niedostępny. Niedodatnia liczba sekund wskazuje na niedostępność stałą. Nie jest wykonywana żadna próba obliczenia czasu określonego od zgłoszenia wyjątku.

isPermanent()

public boolean isPermanent()

Zwraca true, jeżeli serwlet jest niedostępny stale, a w przeciwnym wypadku false.

2 Część I ♦ Podstawy obsługi systemu WhizBang (Nagłówek strony)

2 C:\0-praca\Java Servlet - programowanie. Wyd. 2\rA-t.doc

---