OverviewThis project will address the situation where a client either can not, or prefers to not use Header variables for declaring the a Request's or Response's mime-type. This feature would provide an alternative to using HTTP Header variables. This project will allow the client to declare the mime-type by either using a URI "suffix" or by setting a Query Parameter.
This project will also address an issue of an un-declared mime-type. The wildcard "*/*" was used when a mime-type was not set. This project will implement a feature where the default mime-type will be "text/plain". This is really only an issue for those operations that return data (search and read) which use GET. The HTTP Response data would be formatted using the specific suffix.
curl ... /contexts/devel/subjects/ja1324.json
curl ... /contexts/devel/subjects/ja1324.xml
curl ... /contexts/devel/subjects/ja1324.html
curl ... /contexts/devel/subjects/ja1324.plain The HTTP Request data (payload) would be formatted with the specific suffix.
curl -X POST ... /contexts/embedded/subjects.json
curl -X POST ... /contexts/embedded/subjects.xml The HTTP Request data (payload) would be formatted with the specific suffix.
curl -X PUT ... /contexts/devel/subjects/ja1324.json
curl -X PUT ... /contexts/devel/subjects/ja1324.xml The HTTP Response data would be formatted using the specific suffix. curl ... /contexts/devel/subjects/ja1324\?fomat=json
curl ... /contexts/devel/subjects/ja1324\?format=xml
curl ... /contexts/devel/subjects/ja1324\?fomat=html
curl ... /contexts/devel/subjects/ja1324\?format=plain
The HTTP Request data (payload) would be formatted with the specific suffix. curl -X POST ... /contexts/embedded/subjects\?format=json
curl -X POST ... /contexts/embedded/subjects\?format=xml
The HTTP Request data (payload) would be formatted with the specific suffix. curl -X PUT ... /contexts/devel/subjects/ja1324\?format=json
curl -X PUT ... /contexts/devel/subjects/ja1324\?format=xml
A ServletFilter will be created to check the URI for the format query parameter. The ServletFilter will add Header variables to the HTTP Request. If a query parameter is used, it will be removed. If a suffix was used, it will be removed. The ServletFilter will be configurable via the web.xml file. It supports the following modes:
Mode | Description | disabled | The ServletFilter is not enabled, it will be skipped. This is the default. | parameter | The ServletFilter will look for a valid query parameter with the name format. If it is found, it will use the value to set the Accept and/or Content-Type HTTP header variable. Here are the valid query parameter values:
| suffix | The ServletFilter will look for a suffix appended to the end of the URI. If a valid suffix is found, the suffix value will be used to set the Accept and/or Content-Type HTTP header variable. Here are the valid suffixes:
| both | The ServletFilter will look for the query parameter format and for a suffix. The ServletFilter checks for a suffix first. If a suffix is found, it's value will be used to set the mimeType. The suffix ServletFilter then checks for the format query parameter. If the query parameter is found, it's value is used to set the mimeType. If both are found, the query parameter value will override the suffix value. |
Here is the logic for which mechanism will be used. - If nothing is set, an internal default is used
- If only Header, the header is used
- If a Header and a Suffix, the suffix is used
- If a Header and a Param, the param is used
- If a Suffix and a Param, the param is used
- If a Header and Suffix and Param, the param is used
The "X" indicates a valid mime-type
Header | Suffix | Param | Actually Used | | | | Default | X | | | Header | | X | | Suffix | X | X | | Suffix | | | X | Param | X | | X | Param | | X | X | Param | X | X | X | Param |
LimitationsThe top level REST paths do not support the use of a suffix to specify the mime-type. The mime-type can still be set with the Header variable or with the query parameter "format". The following URIs do not support the suffix mechanism.
clients | .../resources/clients.json | contexts | .../resources/contexts.xml
| engine | .../resources/engine.json | sessioninfo | .../resources/sessioninfo.xml |
Notice: this is only the top level. Sub path element do work with the suffix mechanism.
Here are the support suffix values:
The following URIs support the use of a suffix
Syntax | Example | contexts/{contextid}[suffix] | contexts/Employees-Embed-JDBC.json | contexts/{contextid}/subjects[suffix] | contexts/Employees-Embed-JDBC/subjects.xml | contexts/{contextid}/subjects/{subjectid}[suffix] | contexts/Employees-Embed-JDBC/subjects/ja1324.html |
The following URL is submitted ...
curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/ja1324.json
Notice the following changes: - Before
- The path had '.json' as a suffix
- The Header variable 'accept' is '*/*'
- After
- The path no longer has the '.json' suffix
- The Header variable 'accept' is 'application/json'
Here are the support suffix values: - ?format=xml
- ?format=json
- ?format=html
- ?format=plain
The following URIs support the use of a Query Parameter
Syntax | Example | contexts/{contextid}\?format=[format] | contexts/Employees-Embed-JDBC\?format=xml | contexts/{contextid}/subjects\?format=[format] | contexts/Employees-Embed-JDBC/subjects\?format=xml | contexts/{contextid}/subjects/{subjectid}\?format=[format] | contexts/Employees-Embed-JDBC/subjects/ja1324\?format=html |
The following URL is submitted ...
curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/ja1324\?format=json
Classes- MimeTypeHeaderFilter
- Extends BaseFilter
- Leverages web.xml init param for configuration:
- mode: disabled, parameter, suffix, both
- debug: 0, 1, 2, 3, 4
- Uses the MimeTypeHeaderRequestWrapper
- MimeTypeHeaderRequestWrapper
- Checks for the query parameter: format
- Overloads methods
- String getHeader(String name)
- Enumeration<String> getHeaders(String name)
- Enumeration<String> getHeaderNames()
- String getContentType()
- String getQueryString()
- String getParameter(String name)
- Map<String, String[]> getParameterMap()
- Enumeration getParameterNames()
- String[] getParameterValues(String name)
- String getPathInfo()
- String getRequestURI()
- StringBuffer getRequestURL()
- ServletInputStream getInputStream() throws IOException
- BufferedReader getReader() throws IOException
Configuration
web.xml
<filter>
<description>processes HTTP query parameters</description>
<filter-name>MimeTypeHeader</filter-name>
<filter-class>org.openptk.servlet.filters.MimeTypeHeaderFilter</filter-class>
<init-param>
<param-name>mode</param-name>
<param-value>disabled</param-value> <!-- disabled, parameter, suffix, both -->
</init-param>
<init-param>
<param-name>debug</param-name>
<param-value>2</param-value> <!-- 0, 1, 2, 3, 4 -->
</init-param>
</filter>
Logincurl -c cookies.txt http://localhost:8080/openptk-server/login?user=openptkconfig\&password=password\&clientid=identitycentral
Query ParameterCreatecurl -X POST -v -b cookies.txt -d '{"subject" : { "attributes" : { "lastname" : "Bauer", "title" : "Agent", "firstname" : "Jack", "telephone" : "123-456-7890", "email" : "jack@ctu.gov" }}}' http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects\?format=json
Readcurl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/jbauer\?format=json
curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/jbauer\?format=xml
curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/jbauer\?format=plain
curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/jbauer\?format=html
Updatecurl -X PUT -v -b cookies.txt -d '{ "subject" : { "attributes" : { "title" : "Super Agent" } } }' http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/jbauer\?format=json Searchcurl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects\?format=json\&search=jack curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects\?format=xml\&search=jack
curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects\?format=plain\&search=jack
curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects\?format=html\&search=jack
SuffixCreatecurl -X POST -v -b cookies.txt -d '{"subject" : { "attributes" : { "lastname" : "Cauer", "title" : "Agent", "firstname" : "Jack", "telephone" : "123-456-7890", "email" : "jack@ctu.gov" }}}' http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects.json
Readcurl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/jcauer.json
curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/jcauer.xml
curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/jcauer.plain
curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/jcauer.html
curl -X PUT -v -b cookies.txt -d '{ "subject" : { "attributes" : { "title" : "Super Agent" } } }' http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/jcauer.json Searchcurl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects.json\?search=jack
curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects.xml\?search=jack
curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects.plain\?search=jack
curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects.html\?search=jack
|
|