1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
|
<?xml version='1.0' encoding='UTF-8'?>
<!--
* Copyright 2001-2004 The Apache Software Foundation.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
-->
<!DOCTYPE s1 SYSTEM 'dtd/document.dtd'>
<s1 title='Socket Samples'>
<s2 title='Overview'>
<p>
Very often, applications need to transmit XML documents over
the network using a socket stream. However, XML is not designed
to make this possible because XML documents do not contain an
explicit end-of-document terminal. Therefore, the stream must
end (i.e. the socket must close) in order for the parser to
finish parsing the complete XML document.
</p>
<p>
Since creating socket streams is expensive the application needs
to re-use the same stream but XML doesn't define an end-of-document.
Therefore, another solution must be found. The socket samples
included with Xerces can be used to learn how to overcome this
common problem in a general way.
</p>
<p>Socket samples:</p>
<ul>
<li><link anchor='DelayedInput'>socket.DelayedInput</link></li>
<li><link anchor='KeepSocketOpen'>socket.KeepSocketOpen</link></li>
</ul>
</s2>
<anchor name='DelayedInput'/>
<s2 title='Sample socket.DelayedInput'>
<p>
This sample delays the input to the SAX parser to simulate reading data
from a socket where data is not always immediately available. An XML
parser should be able to parse the input and perform the necessary
callbacks as data becomes available. So this is a good way to test
any parser that implements the SAX2 <code>XMLReader</code> interface
to see if it can parse data as it arrives.
</p>
<p>
<strong>Note:</strong> This sample uses NSGMLS-like output of elements
and attributes interspersed with information about how many bytes are
being read at a time.
</p>
<s3 title='usage'>
<source>java socket.DelayedInput (options) filename ...</source>
</s3>
<s3 title='options'>
<table>
<tr><th>Option</th><th>Description</th></tr>
<tr><td>-p name</td><td>Select SAX2 parser by name.</td></tr>
<tr><td>-n | -N</td><td>Turn on/off namespace processing.</td></tr>
<tr><td>-v | -V</td><td>Turn on/off validation.</td></tr>
<tr>
<td>-s | -S</td>
<td>
Turn on/off Schema validation support.<br/>
<strong>NOTE:</strong> Not supported by all parsers.");
</td>
</tr>
<tr>
<td>-f | -F</td>
<td>
Turn on/off Schema full checking.<br/>
<strong>NOTE:</strong> Requires use of -s and not supported by all parsers.
</td>
</tr>
<tr><td>-h</td><td>Display help screen.</td></tr>
</table>
</s3>
</s2>
<anchor name='KeepSocketOpen'/>
<s2 title='Sample socket.KeepSocketOpen'>
<p>
This sample provides a solution to the problem of 1) sending multiple
XML documents over a single socket connection or 2) sending other types
of data after the XML document without closing the socket connection.
</p>
<p>
The first situation is a problem because the XML specification does
not allow a document to contain multiple root elements. Therefore a
document stream must end (or at least appear to end) for the XML
parser to accept it as the end of the document.
</p>
<p>
The second situation is a problem because the XML parser buffers the
input stream in specified block sizes for performance reasons. This
could cause the parser to accidentally read additional bytes of data
beyond the end of the document. This actually relates to the first
problem if the documents are encoding in two different international
encodings.
</p>
<p>
The solution that this sample introduces wraps both the input and
output stream on both ends of the socket. The stream wrappers
introduce a protocol that allows arbitrary length data to be sent
as separate, localized input streams. While the socket stream
remains open, a separate input stream is created to "wrap" an
incoming document and make it appear as if it were a standalone
input stream.
</p>
<p>
To use this sample, enter any number of filenames of XML documents
as parameters to the program. For example:
</p>
<source>java socket.KeepSocketOpen doc1.xml doc2.xml doc3.xml</source>
<p>
This program will create a server and client thread that communicate
on a specified port number on the "localhost" address. When the client
connects to the server, the server sends each XML document specified
on the command line to the client in sequence, wrapping each document
in a <code>WrappedOutputStream</code>. The client uses a
<code>WrappedInputStream</code> to read the data and pass it to the
parser.
</p>
<note>
Do not send any XML documents with associated grammars to the client.
In other words, don't send any documents that contain a DOCTYPE line
that references an external DTD because the client will not be able
to resolve the location of the DTD and an error will be issued by
the client.
</note>
</s2>
</s1>
|
