V době psaní tohoto článku se většina webových služeb skládá z jednoduchých výměn zpráv: Klient kontaktuje webovou službu a odešle jí zprávu. Webová služba zase tento požadavek zpracuje a poté odešle zpět odpověď klientovi. Tento jednoduchý vzor požadavku / odpovědi modeluje způsob, jakým protokol HTTP usnadňuje interakce mezi klientem a webovým serverem. Stejně jako u protokolu HTTP musí výměny zpráv webové služby často zahrnovat binární obsah, například obrázky, dokumenty nebo zvukové klipy. Tento článek představuje odesílání a přijímání obsahu binárních webových služeb pomocí protokolu SOAP (Simple Object Access Protocol) s rozhraním Attachments API for Java (SAAJ) 1.2.
Než se ponoříme do složitosti přenosu obsahu binární webové služby, stojí za to zdůraznit, že jednoduchá webová služba ve stylu požadavku / odezvy kontrastuje se službami, které vytvářejí interakci klient / server jako vzdálené volání procedur nebo RPC. V RPC server vystavuje rozhraní, které se podobá API. Klient zase vyvolá takovou službu tak, že provede vzdálená volání na API služby, předá požadované parametry a přijme hodnoty, které volání vytvoří.
RPC založené na XML se podobá způsobu, jakým vyvoláváte objekty v objektově orientovaném systému (OO). Při práci s rozhraním Java API pro RPC založené na XML (JAX-RPC) si málokdy uvědomíte, že pracujete s dokumenty XML, nikoli s objekty Java. JAX-RPC vám umožní přemýšlet o webových službách jako o vzdálených objektech, stejně jako s Java RMI (Remote Method Invocation). Modul runtime JAX-RPC překládá volání metody OO na vysoké úrovni na dokumenty XML očekávané vzdálenou webovou službou. Zatímco webové služby ve stylu RPC často poskytují pohodlnější programovací model, volání RPC se při výměně zpráv XML, které tvoří vzdálené volání, musí také spoléhat na vrstvu zasílání zpráv na nižší úrovni.
U některých webových služeb je často užitečné přímo programovat na tuto vrstvu zpráv nižší úrovně. Například pokud si přejete vyvolat webovou službu, která spotřebovává doklad o objednávce a vrátí potvrzení, můžete tuto výměnu dokumentů snadno modelovat jako jednu výměnu zpráv s požadavkem / odpovědí. Místo vytváření vzdálených volání metod byste vytvářeli zprávy XML, odesílali je přímo do webové služby a zpracovávali XML odpověď služby, pokud nějaká existuje. Vzhledem k tomu, že SOAP definuje běžný formát zpráv pro zprávy webové služby, budete muset vytvořit zprávy vyhovující protokolu SOAP a jakmile služba odpoví, analyzovat tyto zprávy odpovědi SOAP zpět do formátu, kterému váš program rozumí.
SAAJ poskytuje pohodlnou knihovnu pro vytváření a čtení zpráv SOAP a také vám umožňuje odesílat a přijímat zprávy SOAP v síti. SAAJ definuje jmenný prostor javax.xml.soap. Třídy, které jsou umístěny v tomto balíčku, původně tvořily část Java API pro XML Messaging (JAXM), ale byly nedávno odděleny do jejich vlastního API. JAXM spoléhá na SAAJ pro konstrukci a manipulaci se zprávami SOAP a přidává spolehlivost zpráv a další funkce specifické pro zasílání zpráv XML. Zatímco SAAJ je požadovanou součástí J2EE (Java 2 Platform, Enterprise Edition) 1.4, JAXM není. Tento článek se zaměřuje na jeden z nejužitečnějších aspektů SAAJ: schopnost připojit ke zprávě SOAP binární obsah.
Výhody příloh
Zatímco návrhové centrum SOAP se zaměřuje na zapouzdření dokumentů XML ve zprávě, funkce přílohy SOAP rozšiřuje zprávu SOAP tak, aby kromě běžné části SOAP obsahovala i nula nebo více příloh, jak ukazuje obrázek 1. Každá příloha je definována typem MIME a může předpokládat jakýkoli obsah reprezentovaný jako bajtový proud.
Funkce připojení SOAP se osvědčuje jako nejužitečnější, když si klient přeje přenést binární data, jako jsou obrazová nebo zvuková data, do webové služby. Bez příloh SOAP by se odeslání části binárních dat ukázalo jako obtížnější. Například zpráva SOAP klienta by mohla zprostředkovat adresu URL binárního souboru. Klient by poté musel provozovat server HTTP, aby umožnil webové službě načíst tento soubor. To by představovalo nepřiměřenou zátěž pro každého klienta webových služeb, zejména pro klienty běžící na zařízeních s omezenými prostředky, jako jsou digitální fotoaparáty nebo skenery. Funkce připojení SOAP umožňuje každému klientovi webové služby, který je schopen přenášet zprávy SOAP, vložit binární soubory přímo do zprávy SOAP.
Například přílohy SOAP se ukázaly jako užitečné při interakci s webovými stránkami portálu. Zvažte síť realitních kanceláří, která potřebuje distribuovat popisy a fotografie domů k prodeji na centralizovaný portál pro vyhledávání nemovitostí. Pokud portál provozuje servlet umožňující zveřejňování zpráv SOAP s přílohami, mohla by realitní kancelář aktualizovat své výpisy několika zprávami SOAP, včetně fotografií těchto domů. Tělo zprávy SOAP může vložit popis vlastnosti a přílohy SOAP mohou nést soubory obrázků. V tomto scénáři, když servlet provozovatele portálu obdrží takovou zprávu, vrátí dokument s potvrzením označující dostupnost příspěvku na portálu. Obrázek 2 ilustruje takovou webovou službu.
Anatomie protokolu SOAP s přílohami
Zprávy SOAP s přílohami W3C (World Wide Web Consortium) Poznámka (viz Zdroje) nepřidává do SOAP nové funkce. Spíše definuje, jak využít typů MIME ve zprávě SOAP k definování příloh a jak odkazovat na tyto přílohy z těla SOAP.
Typ MIME vícedílný / související definuje dokumenty skládající se z několika souvisejících částí. Zprávy SOAP s přílohami musí následovat vícedílné / související Typ MIME. Následující příklad ukazuje a vícedílné / související Zpráva SOAP, vázaná na protokol HTTP, se dvěma přílohami:
POST / propertyListing HTTP / 1.1 Host: www.realproperties.com Content-Type: Multipart / Related; hranice = MIME_boundary; typ = text / xml; Délka obsahu: NNNN - MIME_boundary Typ obsahu: text / xml; charset = UTF-8 Content-Transfer-Encoding: 8bit Content-ID: Really Nice Homes, Inc. Add 1234 Main St Pleasantville CA 94323 250000 --MIME_boundary Content-Type: image / jpeg Content-ID: .... JPEG DATA ..... --MIME_boundary Content-Type: image / jpeg Content-ID: .... JPEG DATA ..... --MIME_boundary--
Výše uvedená vícedílná zpráva obsahuje řadu záhlaví MIME a souvisejících dat. V kořenovém adresáři dokumentu je tělo protokolu SOAP. Protože tělo SOAP obsahuje pouze data XML, je typ MIME celé zprávy text / xml. Za obálkou SOAP následují dvě přílohy, z nichž každá odpovídá obrazovému souboru odeslanému spolu se zprávou.
ID obsahu identifikuje každou přílohu. Poznámka W3C umožňuje buď ID obsahu, nebo umístění obsahu odkazovat na přílohy, ale dává přednost tomu prvnímu. Taková ID obsahu fungují jako odkazy na přílohy Uniform Resource Identifier (URI); pravidla kódování SOAP 1.1 definují, jak odkazovat na prostředek ve zprávě SOAP prostřednictvím identifikátoru URI, který může odkazovat na jakýkoli obsah, nejen na XML (viz část 5 protokolu SOAP 1.1 v Zdrojích). Procesor SOAP řeší tyto odkazy URI při zpracování zprávy. Na základě výše uvedeného příkladu SOAP procesor přidruží prvek přední obrázek s datovou částí s Content ID [email protected] ve zprávě SOAP.
Vytvořte a odešlete zprávu SOAP s přílohami
SAAJ umožňuje vytvářet a upravovat libovolnou část zprávy SOAP, včetně příloh. Většina SAAJ je založena na abstraktních třídách a rozhraních, takže každý poskytovatel může implementovat SAAJ do svých vlastních produktů. Referenční implementace Sun Microsystems přichází s balíčkem Java Web Services Developer Pack (JWSDP).
Jelikož zprávy SOAP představují pouze zvláštní formu dokumentů XML, staví JAAS na zpracování XML na rozhraní API modelu Document Object Model (DOM). Většina komponent zprávy SOAP sestupuje z javax.xml.soap.Node rozhraní, které je zase a org.w3c.dom.Node podtřída. Podtřídy SAAJ Uzel přidat konstrukce specifické pro SOAP. Například speciální Uzel, SOAPElement, představuje prvek zprávy SOAP.
Přímým výsledkem spoléhání SAAJ na rozhraní a abstraktní třídy je, že většinu úkolů souvisejících se SOAP splníte pomocí továrních metod. Chcete-li připojit svou aplikaci k SAAJ API, nejprve vytvořte SOAPConnection od a SOAPConnectionFactory. Pro vytváření a úpravy zpráv SOAP můžete také inicializovat a MessageFactory a SOAPFactory. MessageFactory umožňuje vytvářet zprávy SOAP a SOAPFactory poskytuje metody pro vytvoření jednotlivých částí zprávy SOAP:
SOAPConnectionFactory spConFactory = SOAPConnectionFactory.newInstance (); SOAPConnection con = spConFactory.createConnection (); SOAPFactory soapFactory = SOAPFactory.newInstance ();
Díky těmto nástrojům můžete vytvořit zprávu SOAP, kterou by klient z realitní kanceláře použil k odeslání aktualizace výpisu na web portálu.
SAAJ nabízí několik způsobů, jak vytvořit novou zprávu SOAP. Následující příklad ukazuje nejjednodušší metodu, která vytvoří prázdnou zprávu SOAP s obálkou a hlavičkou a tělem v této obálce. Protože v této zprávě nepotřebujete záhlaví SOAP, můžete tento prvek ze zprávy odebrat:
Zpráva SOAPMessage = factory.createMessage (); Záhlaví SOAPHeader = message.getSOAPHeader (); header.detachNode ();
Přidání struktury XML do těla zprávy se ukazuje jako přímočaré:
Tělo SOAPBody = message.getSOAPBody (); Název listingElementName = soapFactory.createName ("propertyListing", "realProperty", "//schemas.realhouses.com/listingSubmission"); SOAPBodyElement listingElement = body.addBodyElement (listingElementName); Jméno attname = soapFactory.createName ("id"); listingElement.addAttribute (attname, "property_1234"); SOAPElement listingAgency = listingElement.addChildElement ("listingAgency"); listingAgency.addTextNode ("Really Nice Homes, Inc"); SOAPElement listingType = listingElement.addChildElement ("listingType"); listingType.addTextNode ("přidat"); SOAPElement propertyAddress = listingElement.addChildElement ("propertyAddress"); SOAPElement street = propertyAddress.addChildElement ("ulice"); street.addTextNode ("1234 Main St"); SOAPElement city = propertyAddress.addChildElement ("city"); city.addTextNode ("Pleasantville"); SOAPElement state = propertyAddress.addChildElement ("state"); state.addTextNode ("CA"); SOAPElement zip = propertyAddress.addChildElement ("zip"); zip.addTextNode ("94521"); SOAPElement listPrice = listingElement.addChildElement ("listPrice"); listPrice.addTextNode ("25000"); Všimněte si, že do ID přidáte jedinečné ID vlastnosti seznam nemovitostí živel. Dále splňujete podmínky seznam nemovitostí prvek s a QNamenebo název podporující jmenný prostor.
Přílohy ke zprávě SOAP můžete přidat několika způsoby. V tomto příkladu nejprve vytvoříte prvky, které označují přední a vnitřní obrázek uvedené vlastnosti. Každý z nich má href atribut označující ID obsahu přílohy:
Řetězec frontImageID = "[email protected]"; SOAPElement frontImRef = listingElement.addChildElement ("frontImage"); Název hrefAttName = soapFactory.createName ("href"); frontImRef.addAttribute (hrefAttName, frontImageID); Řetězec interiorID = "[email protected]"; SOAPElement interiorImRef = listingElement.addChildElement ("interiorImage"); interiorImRef.addAttribute (hrefAttName, interiorID);
Chcete-li ke zprávě snadno připojit požadované obrazové soubory, použijte a javax.activation.DataHandler objekt z prostředí JavaBeans Activation Framework. DataHandler může automaticky detekovat datový typ, který mu byl předán, a může proto automaticky přiřadit příslušný typ obsahu MIME k příloze:
URL url = nová URL ("file: ///export/files/pic1.jpg"); DataHandler dataHandler = nový DataHandler (url); AttachmentPart att = message.createAttachmentPart (dataHandler); att.setContentId (frontImageID); message.addAttachmentPart (att); Případně můžete předat Objekt, spolu se správným typem MIME, do createAttachmentPart (). Tato metoda se podobá té první. Interně bude implementace SAAJ pravděpodobně hledat a DataContentHandler zpracovat zadaný typ MIME. Pokud nemůže najít vhodného psovoda, createAttachmentPart () hodí IllegalArgumentException:
URL url2 = nová URL ("file: ///export/files/pic2.jpg"); Obrázek im = Toolkit.getDefaultToolkit (). CreateImage (url2); AttachmentPart att2 = message.createAttachmentPart (im, "image / jpeg"); att2.setContentId (ID interiéru); message.addAttachmentPart (att2);
