På dette tidspunkt består de fleste webtjenester af simpel meddelelsesudveksling: En klient kontakter en webtjeneste og sender en besked til den pågældende tjeneste. Webtjenesten behandler til gengæld denne anmodning og sender derefter et svar tilbage til klienten. Det enkle anmodnings- / svarmønster modellerer den måde, hvorpå HTTP-protokollen letter klient- / webserverinteraktioner. Som med HTTP skal udveksling af webservicemeddelelser ofte omfatte binært indhold, såsom billeder, dokumenter eller lydklip. Denne artikel introducerer afsendelse og modtagelse af binært webtjenesteindhold ved hjælp af SOAP (Simple Object Access Protocol) med Attachments API for Java (SAAJ) 1.2.
Før du dykker ind i vanskelighederne ved overførsel af binært webtjenesteindhold, er det værd at påpege, at en simpel anmodning / svar-stil-webtjeneste står i kontrast til tjenester, der former klient / server-interaktion som opkald til fjernprocedurer eller RPC'er. I en RPC udsætter en server en grænseflade, der ligner en API. Til gengæld påkalder en klient en sådan tjeneste ved at foretage fjernopkald på tjenestens API, videregive de krævede parametre og modtage de værdier, som opkaldet producerer.
XML-baseret RPC ligner den måde, du påberåber objekter i et objektorienteret (OO) system. Når du arbejder med Java API til XML-baseret RPC (JAX-RPC), bliver du sjældent opmærksom på, at du arbejder med XML-dokumenter, ikke Java-objekter. JAX-RPC lader dig tænke på webtjenester som eksterne objekter, ligesom du ville med Java RMI (Remote Method Invocation). JAX-RPC runtime oversætter OO-metodeopkald på højt niveau til de XML-dokumenter, der forventes af den eksterne webservice. Mens RPC-stil-webtjenester ofte leverer en mere bekvem programmeringsmodel, skal RPC-opkald også stole på et beskedningslag på lavere niveau for at udveksle de XML-meddelelser, der udgør fjernopkaldet.
For nogle webtjenester er det ofte nyttigt at programmere direkte til det lavere niveau for beskedlag. For eksempel, hvis du ønsker at påkalde en webtjeneste, der bruger et indkøbsordredokument og returnerer en kvittering, kan du nemt modellere dokumentudvekslingen som en enkelt anmodning / svarudveksling. I stedet for at foretage eksterne metodeopkald vil du konstruere XML-meddelelser, sende disse meddelelser direkte til en webtjeneste og behandle tjenestens XML-svar, hvis der findes nogen. Da SOAP definerer det fælles beskedformat for webservicemeddelelser, skal du konstruere SOAP-konforme meddelelser, og når tjenesten reagerer, skal du analysere disse SOAP-svarmeddelelser tilbage i et format, som dit program forstår.
SAAJ giver et praktisk bibliotek til at konstruere og læse SOAP-meddelelser og giver dig også mulighed for at sende og modtage SOAP-meddelelser over hele netværket. SAAJ definerer navneområdet javax.xml.sæbe. Klasser, der findes i denne pakke, oprindeligt var en del af Java API til XML Messaging (JAXM), men blev for nylig adskilt i deres egen API. JAXM er afhængig af SAAJ til SOAP-meddelelseskonstruktion og -manipulation og tilføjer pålidelighed og andre funktioner, der er specifikke for XML-beskeder. Mens SAAJ er en påkrævet komponent i J2EE (Java 2 Platform, Enterprise Edition) 1.4, er JAXM ikke. Denne artikel fokuserer på et af SAAJs mest nyttige aspekter: evnen til at vedhæfte binært indhold til en SOAP-besked.
Fordelene ved vedhæftede filer
Mens SOAPs designcenter fokuserer på at indkapsle XML-dokumenter i en meddelelse, udvider SOAPs vedhæftningsfunktion en SOAP-meddelelse til at omfatte ud over den almindelige SOAP-del nul eller flere vedhæftede filer, som figur 1 viser. Hver vedhæftet fil er defineret af en MIME-type og kan antage ethvert indhold, der er repræsenteret som en byte-stream.
SOAPs vedhæftningsfunktion viser sig at være mest nyttig, når en klient ønsker at overføre binære data, såsom et billede eller lyddata, til en webtjeneste. Uden SOAP-vedhæftede filer ville det være vanskeligere at sende et stykke binære data. For eksempel kunne en klients SOAP-meddelelse formidle den binære fils URL-adresse. Klienten bliver derefter nødt til at betjene en HTTP-server for at lade webservicen hente den fil. Det ville udgøre en unødig byrde for enhver webtjeneste-klient, især for klienter, der kører på enheder med begrænset ressource, såsom digitale kameraer eller scannere. SOAPs vedhæftningsfunktion lader enhver webtjeneste-klient, der er i stand til at sende SOAP-meddelelser integrere binære filer direkte i en SOAP-besked.
SOAP-vedhæftede filer viser sig f.eks. Praktisk, når de interagerer med portalwebsteder. Overvej et ejendomsmæglernetværk, der skal distribuere beskrivelser og fotografier af huse til salg til en centraliseret ejendomssøgningsportal. Hvis portalen driver en servlet, der tillader udstationering af SOAP-meddelelser med vedhæftede filer, kan et ejendomsmægler opdatere sine lister med et par SOAP-meddelelser, herunder fotos af disse hjem. SOAP-meddelelseslegemet kan integrere egenskabsbeskrivelsen, og SOAP-vedhæftede filer kan bære billedfilerne. Under dette scenario, når en portaloperatørs servlet modtager en sådan besked, ville den returnere et bekræftelsesdokument, der angiver postens tilgængelighed på portalen. Figur 2 illustrerer en sådan webtjeneste.
Anatomien til SOAP med meddelelser om vedhæftede filer
SOAP-meddelelser med vedhæftede filer W3C (World Wide Web Consortium) Bemærk (se Ressourcer) tilføjer ikke nye funktioner til SOAP. Det definerer snarere, hvordan man drager fordel af MIME-typer i en SOAP-besked til at definere vedhæftede filer, og hvordan man henviser til disse vedhæftede filer fra SOAP-kroppen.
MIME-typen multipart / relateret definerer dokumenter, der består af flere relaterede dele. SOAP-meddelelser med vedhæftede filer skal følge multipart / relateret MIME-type. Eksemplet nedenfor viser a multipart / relateret SOAP-meddelelse, bundet til HTTP-protokollen, med to vedhæftede filer:
POST / propertyListing HTTP / 1.1 Host: www.realproperties.com Content-Type: Multipart / Related; grænse = MIME_grænse; type = tekst / xml; Indholdslængde: NNNN --MIME_boundary Indholdstype: tekst / xml; charset = UTF-8 Content-Transfer-Encoding: 8bit Content-ID: Really Nice Homes, Inc. Tilføj 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--
Ovenstående meddelelse med flere dele omfatter en række MIME-headere og relaterede data. Ved roden til dokumentet er SOAP-kroppen. Da SOAP-kroppen kun indeholder XML-data, er MIME-typen for hele meddelelsen tekst / xml. Efter SOAP-konvolutten er der to vedhæftede filer, der hver svarer til en billedfil sendt sammen med beskeden.
Et indholds-ID identificerer hver vedhæftet fil. W3C-noten lader enten et indholds-id eller en indholdsplacering henvise til vedhæftede filer, men det foretrækker det førstnævnte. Sådanne indholds-id'er fungerer som URI-referencer (Uniform Resource Identifier) til vedhæftede filer; SOAP 1.1-kodningsreglerne definerer, hvordan man henviser til en ressource i en SOAP-meddelelse via en URI, der kan henvise til ethvert indhold, ikke kun XML (se afsnit 5 i SOAP 1.1 i ressourcer). En SOAP-processor løser disse URI-referencer, når den behandler meddelelsen. Baseret på ovenstående eksempel forbinder SOAP-processoren elementet frontImage med datasektionen med Content ID [email protected] i SOAP-meddelelsen.
Opret og send en SOAP-besked med vedhæftede filer
SAAJ giver dig mulighed for at oprette og redigere enhver del af en SOAP-besked, inklusive vedhæftede filer. Det meste af SAAJ er baseret på abstrakte klasser og grænseflader, så hver udbyder kan implementere SAAJ i sine egne produkter. Sun Microsystems 'referenceimplementering leveres med Java Web Services Developer Pack (JWSDP).
Da SOAP-meddelelser kun repræsenterer en særlig form for XML-dokumenter, bygger JAAS på DOM-API (Document Object Model) til XML-behandling. De fleste SOAP-meddelelseskomponenter stammer fra javax.xml.soap.Node interface, som igen er en org.w3c.dom.Node underklasse. SAAJ-underklasser Node for at tilføje SOAP-specifikke konstruktioner. For eksempel en særlig Node, SOAPElement, repræsenterer et SOAP-meddelelseselement.
Et direkte resultat af SAAJs afhængighed af grænseflader og abstrakte klasser er, at du udfører de fleste SOAP-relaterede opgaver via fabriksmetoder. For at forbinde din applikation med SAAJ API opretter du først en SOAP-forbindelse fra en SOAPConnectionFactory. Til oprettelse og redigering af SOAP-meddelelser kan du også initialisere a MessageFactory og en SOAPFactory. MessageFactory lader dig oprette SOAP-meddelelser, og SOAPFactory giver metoderne til at oprette individuelle dele af en SOAP-besked:
SOAPConnectionFactory spConFactory = SOAPConnectionFactory.newInstance (); SOAPConnection con = spConFactory.createConnection (); SOAPFactory soapFactory = SOAPFactory.newInstance ();
Med disse værktøjer på plads kan du oprette en SOAP-besked, som en klient fra et ejendomsmægler bruger til at sende en listeopdatering til et portalwebsted.
SAAJ tilbyder flere måder at oprette en ny SOAP-besked på. Følgende eksempel viser den enkleste metode, der opretter en tom SOAP-besked med en konvolut og overskrift og brødtekst i konvolutten. Da du ikke har brug for et SOAP-overskrift i denne meddelelse, kan du fjerne elementet fra meddelelsen:
SOAPMessage-meddelelse = fabrik.createMessage (); SOAPHeader header = message.getSOAPHeader (); header.detachNode ();
Tilføjelse af XML-strukturen til meddelelsesteksten viser sig ligetil:
SOAPBody body = message.getSOAPBody (); Navn listeElementName = soapFactory.createName ("propertyListing", "realProperty", "//schemas.realhouses.com/listingSubmission"); SOAPBodyElement listingElement = body.addBodyElement (listingElementName); Navn attname = soapFactory.createName ("id"); listingElement.addAttribute (attname, "property_1234"); SOAPElement listingAgency = listingElement.addChildElement ("listingAgency"); listingAgency.addTextNode ("Virkelig dejlige hjem, Inc"); SOAPElement listingType = listingElement.addChildElement ("listingType"); listingType.addTextNode ("tilføj"); SOAPElement propertyAddress = listingElement.addChildElement ("propertyAddress"); SOAPElement street = propertyAddress.addChildElement ("street"); street.addTextNode ("1234 Main St"); SOAPElement by = propertyAddress.addChildElement ("by"); city.addTextNode ("Pleasantville"); SOAPElement-tilstand = propertyAddress.addChildElement ("tilstand"); state.addTextNode ("CA"); SOAPElement zip = propertyAddress.addChildElement ("zip"); zip.addTextNode ("94521"); SOAPElement listPrice = listingElement.addChildElement ("listPrice"); listPrice.addTextNode ("25000"); Bemærk, at du tilføjer ejendomens unikke id som en attribut til propertyListing element. Yderligere kvalificerer du dig til propertyListing element med en QName, eller navnebevidst navn.
Du kan tilføje vedhæftede filer til SOAP-meddelelsen på flere måder. I dette eksempel opretter du først elementer til at betegne den angivne ejendoms front- og interiørbilleder. Hver har en href attribut, der angiver vedhæftnings indholds-id:
String frontImageID = "[email protected]"; SOAPElement frontImRef = listingElement.addChildElement ("frontImage"); Navn hrefAttName = soapFactory.createName ("href"); frontImRef.addAttribute (hrefAttName, frontImageID); String interiorID = "[email protected]"; SOAPElement interiorImRef = listingElement.addChildElement ("interiorImage"); interiorImRef.addAttribute (hrefAttName, interiorID);
Brug en for at nemt vedhæfte de krævede billedfiler til meddelelsen javax.activation.DataHandler objekt fra JavaBeans Activation Framework. DataHandler kan automatisk registrere datatypen, der sendes til den, og den kan derfor automatisk tildele den relevante MIME-indholdstype til vedhæftet fil:
URL url = ny URL ("fil: ///export/files/pic1.jpg"); DataHandler dataHandler = ny DataHandler (url); AttachmentPart att = message.createAttachmentPart (dataHandler); att.setContentId (frontImageID); message.addAttachmentPart (att); Alternativt kan du muligvis videregive en Objektsammen med den korrekte MIME-type til createAttachmentPart (). Denne metode ligner den første. Internt vil SAAJ-implementeringen sandsynligvis se efter en DataContentHandler til at håndtere den specificerede MIME-type. Hvis den ikke kan finde en passende handler, createAttachmentPart () vil kaste en IllegalArgumentException:
URL url2 = ny URL ("fil: ///export/files/pic2.jpg"); Billede im = Toolkit.getDefaultToolkit (). CreateImage (url2); AttachmentPart att2 = message.createAttachmentPart (im, "image / jpeg"); att2.setContentId (interiorID); message.addAttachmentPart (att2);
