1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 """A special kind of variable whose value is streamed."""
17
18
20 """IStreamVariable is a special kind of variable whose value is streamed
21 to an L{StringIO} provided by the L{getOutputStream} method. E.g. in web
22 terminals L{IStreamVariable} can be used to send large files from browsers
23 to the server without consuming large amounts of memory.
24
25 Note, writing to the L{OutputStream} is not synchronized by the
26 terminal (to avoid stalls in other operations when eg. streaming to a
27 slow network service or file system). If UI is changed as a side effect
28 of writing to the output stream, developer must handle synchronization
29 manually.
30
31 @author: Vaadin Ltd.
32 @author: Richard Lincoln
33 @version: 1.1.2
34 @see: L{PaintTarget.addVariable}
35 """
36
38 """Invoked by the terminal when a new upload arrives, after
39 L{streamingStarted} method has been called.
40 The terminal implementation will write the streamed variable to the
41 returned output stream.
42
43 @return: Stream to which the uploaded file should be written.
44 """
45 raise NotImplementedError
46
47
49 """Whether the L{onProgress} method should be called during the upload.
50
51 L{onProgress} is called in a synchronized block
52 when the content is being received. This is potentially bit slow,
53 so we are calling that method only if requested. The value is
54 requested after the L{uploadStarted} event, but not after reading each
55 buffer.
56
57 @return: true if this L{IStreamVariable} wants to by notified
58 during the upload of the progress of streaming.
59 @see: L{onProgress}
60 """
61 raise NotImplementedError
62
63
65 """This method is called by the terminal if L{listenProgress}
66 returns true when the streaming starts.
67 """
68 raise NotImplementedError
69
70
72 raise NotImplementedError
73
74
76 raise NotImplementedError
77
78
80 raise NotImplementedError
81
82
84 """If this method returns true while the content is being streamed
85 the Terminal to stop receiving current upload.
86
87 Note, the usage of this method is not synchronized over the
88 Application instance by the terminal like other methods. The
89 implementation should only return a boolean field and especially
90 not modify UI or implement a synchronization by itself.
91
92 @return: true if the streaming should be interrupted as soon as
93 possible.
94 """
95 raise NotImplementedError
96
97
99
101 """@return: the file name of the streamed file if known"""
102 raise NotImplementedError
103
104
106 """@return: the mime type of the streamed file if known"""
107 raise NotImplementedError
108
109
111 """@return: the length of the stream (in bytes) if known, else -1"""
112 raise NotImplementedError
113
114
116 """@return: then number of bytes streamed to IStreamVariable"""
117 raise NotImplementedError
118
119
121 """Event passed to L{uploadStarted} method before the streaming of the
122 content to L{IStreamVariable} starts.
123 """
124
126 """The owner of the IStreamVariable can call this method to inform
127 the terminal implementation that this IStreamVariable will not be
128 used to accept more post.
129 """
130 raise NotImplementedError
131
132
134 """Event passed to L{onProgress} method during the streaming progresses.
135 """
136 pass
137
138
140 """Event passed to L{uploadFinished} method the contents have been
141 streamed to IStreamVariable successfully.
142 """
143 pass
144
145
147 """Event passed to L{uploadFailed} method
148 when the streaming ended before the end of the input. The streaming may
149 fail due an interruption by [] or due an other unknown exception
150 in communication. In the latter case the exception is also passed to
151 L{Application.terminalError}.
152 """
153
155 """@return: the exception that caused the receiving not to finish
156 cleanly"""
157 raise NotImplementedError
158