Package muntjac :: Package terminal :: Module stream_variable
[hide private]
[frames] | no frames]

Source Code for Module muntjac.terminal.stream_variable

  1  # Copyright (C) 2012 Vaadin Ltd.  
  2  # Copyright (C) 2012 Richard Lincoln 
  3  #  
  4  # Licensed under the Apache License, Version 2.0 (the "License");  
  5  # you may not use this file except in compliance with the License.  
  6  # You may obtain a copy of the License at  
  7  #  
  8  #     http://www.apache.org/licenses/LICENSE-2.0  
  9  #  
 10  # Unless required by applicable law or agreed to in writing, software  
 11  # distributed under the License is distributed on an "AS IS" BASIS,  
 12  # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  
 13  # See the License for the specific language governing permissions and  
 14  # limitations under the License. 
 15   
 16  """A special kind of variable whose value is streamed.""" 
 17   
 18   
19 -class IStreamVariable(object):
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
37 - def getOutputStream(self):
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
48 - def listenProgress(self):
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
64 - def onProgress(self, event):
65 """This method is called by the terminal if L{listenProgress} 66 returns true when the streaming starts. 67 """ 68 raise NotImplementedError
69 70
71 - def streamingStarted(self, event):
72 raise NotImplementedError
73 74
75 - def streamingFinished(self, event):
76 raise NotImplementedError
77 78
79 - def streamingFailed(self, event):
80 raise NotImplementedError
81 82
83 - def isInterrupted(self):
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
98 -class IStreamingEvent(object):
99
100 - def getFileName(self):
101 """@return: the file name of the streamed file if known""" 102 raise NotImplementedError
103 104
105 - def getMimeType(self):
106 """@return: the mime type of the streamed file if known""" 107 raise NotImplementedError
108 109
110 - def getContentLength(self):
111 """@return: the length of the stream (in bytes) if known, else -1""" 112 raise NotImplementedError
113 114
115 - def getBytesReceived(self):
116 """@return: then number of bytes streamed to IStreamVariable""" 117 raise NotImplementedError
118 119
120 -class IStreamingStartEvent(IStreamingEvent):
121 """Event passed to L{uploadStarted} method before the streaming of the 122 content to L{IStreamVariable} starts. 123 """ 124
125 - def disposeStreamVariable(self):
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
133 -class IStreamingProgressEvent(IStreamingEvent):
134 """Event passed to L{onProgress} method during the streaming progresses. 135 """ 136 pass
137 138
139 -class IStreamingEndEvent(IStreamingEvent):
140 """Event passed to L{uploadFinished} method the contents have been 141 streamed to IStreamVariable successfully. 142 """ 143 pass
144 145
146 -class IStreamingErrorEvent(IStreamingEvent):
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
154 - def getException(self):
155 """@return: the exception that caused the receiving not to finish 156 cleanly""" 157 raise NotImplementedError
158