Interface FederationV1Api
-
@Path("/_matrix/federation/v1") @Consumes("application/json") @Produces("application/json") public interface FederationV1Api
Matrix homeservers use the Federation APIs (also known as server-server APIs) to communicate with each other. Homeservers use these APIs to push messages to each other in real-time, to request historic messages from each other, and to query profile and presence information about users on each other's servers.
The APIs are implemented using HTTPS GETs and PUTs between each of the servers. These HTTPS requests are strongly authenticated using public key signatures at the TLS transport layer and using public key signatures in HTTP Authorization headers at the HTTP layer.
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
FederationV1Api.QueryProfileField
The field to query.
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
backfill(String roomId, String parentId, Long limit, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
Retrieves a sliding-window history of previous PDUs that occurred on the given room.void
event(String eventId, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
Retrieves a single event.void
eventAuth(String roomId, String eventId, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
Retrieves the complete auth chain for a given event.void
exchangeThirdPartyInvite(String roomId, ThirdPartyInvite request, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
The receiving server will verify the partial m.room.member event given in the request body.void
getMissingEvents(String roomId, Integer limit, Integer minDepth, List<String> earliestEvents, List<String> latestEvents, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
Retrieves previous events that the sender is missing.void
invite(String roomId, String eventId, InviteV1Request request, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
Invites a remote user to a room.void
makeJoin(String roomId, String userId, List<String> ver, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
Asks the receiving server to return information that the sending server will need to prepare a join event to get into the room.void
makeLeave(String roomId, String userId, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
Asks the receiving server to return information that the sending server will need to prepare a leave event to get out of the room.void
onBind(OnBindRequest onBindRequest, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
Used by identity servers to notify the homeserver that one of its users has bound a third party identifier successfully, including any pending room invites the identity server has been made aware of.void
publicRooms(Integer limit, String since, Boolean includeAllNetworks, String thirdPartyInstanceId, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
Gets all the public rooms for the homeserver.void
queryAuth(String roomId, String eventId, QueryAuth request, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
Compares the auth chain provided with what the receiving server has for the room ID and event ID combination.void
queryDirectory(String roomAlias, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
Performs a query to get the mapped room ID and list of resident homeservers in the room for a given room alias.void
queryProfile(String userId, String field, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
Performs a query to get profile information, such as a display name or avatar, for a given user.void
send(String txnId, Transaction transaction, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
Push messages representing live activity to another server.void
sendJoin(String roomId, String eventId, SendRequest request, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
Submits a signed join event to the resident server for it to accept it into the room's graph.void
sendLeave(String roomId, String eventId, SendRequest request, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
Submits a signed leave event to the resident server for it to accept it into the room's graph.void
state(String roomId, String eventId, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
Retrieves a snapshot of a room's state at a given event.void
stateIds(String roomId, String eventId, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
Retrieves a snapshot of a room's state at a given event, in the form of event IDs.void
userDevices(String userId, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
Gets information on all of the user's devices.void
userInfo(String accessToken, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
Exchanges an OpenID access token for information about the user who generated the token.void
userKeysClaim(KeyClaimRequest request, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
Claims one-time keys for use in pre-key messages.void
userKeysQuery(KeyQueryRequest request, javax.ws.rs.core.UriInfo uriInfo, javax.ws.rs.core.HttpHeaders httpHeaders, javax.ws.rs.container.AsyncResponse asyncResponse)
Returns the current devices and identity keys for the given users.
-
-
-
Method Detail
-
send
@PUT @Path("/send/{txnId}") void send(@PathParam("txnId") String txnId, Transaction transaction, @Context javax.ws.rs.core.UriInfo uriInfo, @Context javax.ws.rs.core.HttpHeaders httpHeaders, @Suspended javax.ws.rs.container.AsyncResponse asyncResponse)
Push messages representing live activity to another server. The destination name will be set to that of the receiving server itself. Each embedded PDU in the transaction body will be processed.
Return:List
ofint
andPduProcessingResults
.Status code 200: The result of processing the transaction. The server is to use this response even in the event of one or more PDUs failing to be processed.
- Parameters:
txnId
- Required. The transaction ID.transaction
- transaction data.uriInfo
- Request Information.httpHeaders
- Http headers.asyncResponse
- Asynchronous response.
-
eventAuth
@GET @Path("/event_auth/{roomId}/{eventId}") void eventAuth(@PathParam("roomId") String roomId, @PathParam("eventId") String eventId, @Context javax.ws.rs.core.UriInfo uriInfo, @Context javax.ws.rs.core.HttpHeaders httpHeaders, @Suspended javax.ws.rs.container.AsyncResponse asyncResponse)
Retrieves the complete auth chain for a given event.
Return: List of thePersistedDataUnit
.Status code 200: The auth chain for the event.
- Parameters:
roomId
- Required. The room ID to get the auth chain for.eventId
- Required. The event ID to get the auth chain of.uriInfo
- Request Information.httpHeaders
- Http headers.asyncResponse
- Asynchronous response.
-
queryAuth
@POST @Path("/query_auth/{roomId}/{eventId}") void queryAuth(@PathParam("roomId") String roomId, @PathParam("eventId") String eventId, QueryAuth request, @Context javax.ws.rs.core.UriInfo uriInfo, @Context javax.ws.rs.core.HttpHeaders httpHeaders, @Suspended javax.ws.rs.container.AsyncResponse asyncResponse)
Compares the auth chain provided with what the receiving server has for the room ID and event ID combination.
The auth difference can be calculated in two parts, where the "remote auth" is the auth chain provided by the sending server and the "local auth" is the auth chain the receiving server has. With those lists, the algorithm works bottom-up after sorting each chain by depth then by event ID. The differences are then discovered and returned as the response to this API call.
Return:QueryAuth
. Requires auth: Yes.Status code 200: The auth chain differences, as determined by the receiver.
- Parameters:
roomId
- Required. The room ID to compare the auth chain in.eventId
- Required. The event ID to compare the auth chain of.request
- Request JSON body.uriInfo
- Request Information.httpHeaders
- Http headers.asyncResponse
- Asynchronous response.
-
backfill
@GET @Path("/backfill/{roomId}") void backfill(@PathParam("roomId") String roomId, @QueryParam("v") String parentId, @QueryParam("limit") Long limit, @Context javax.ws.rs.core.UriInfo uriInfo, @Context javax.ws.rs.core.HttpHeaders httpHeaders, @Suspended javax.ws.rs.container.AsyncResponse asyncResponse)
Retrieves a sliding-window history of previous PDUs that occurred on the given room. Starting from the PDU ID(s) given in the "v" argument, the PDUs that preceded it are retrieved, up to a total number given by the "limit".
Return:Transaction
.Status code 200: A transaction containing the PDUs that preceded the given event(s), including the given event(s), up to the given limit.
- Parameters:
roomId
- Required. The room ID to backfill.parentId
- Required. The event IDs to backfill from.limit
- Required. The maximum number of PDUs to retrieve, including the given events.uriInfo
- Request Information.httpHeaders
- Http headers.asyncResponse
- Asynchronous response.
-
getMissingEvents
@POST @Path("/get_missing_events/{roomId}") void getMissingEvents(@PathParam("roomId") String roomId, @QueryParam("limit") Integer limit, @QueryParam("min_depth") Integer minDepth, @QueryParam("earliest_events") List<String> earliestEvents, @QueryParam("latest_events") List<String> latestEvents, @Context javax.ws.rs.core.UriInfo uriInfo, @Context javax.ws.rs.core.HttpHeaders httpHeaders, @Suspended javax.ws.rs.container.AsyncResponse asyncResponse)
Retrieves previous events that the sender is missing. This is done by doing a breadth-first walk of the prev_events for the latest_events, ignoring any events in earliest_events and stopping at the limit.
Requires auth: Yes. Return: List of theList
of thePersistedDataUnit
.Status code 200: The previous events for latest_events, excluding any earliest_events, up to the provided limit.
- Parameters:
roomId
- Required. The room ID to search in.limit
- The maximum number of events to retrieve. Defaults to 10.minDepth
- The minimum depth of events to retrieve. Defaults to 0.earliestEvents
- Required. The latest event IDs that the sender already has. These are skipped when retrieving the previous events of latest_events.latestEvents
- Required. The event IDs to retrieve the previous events for.uriInfo
- Request Information.httpHeaders
- Http headers.asyncResponse
- Asynchronous response.
-
state
@GET @Path("/state/{roomId}") void state(@PathParam("roomId") String roomId, @QueryParam("event_id") String eventId, @Context javax.ws.rs.core.UriInfo uriInfo, @Context javax.ws.rs.core.HttpHeaders httpHeaders, @Suspended javax.ws.rs.container.AsyncResponse asyncResponse)
Retrieves a snapshot of a room's state at a given event.
Return:StateResponse
. Requires auth: Yes.Status code 200: The fully resolved state for the room, prior to considering any state changes induced by the requested event. Includes the authorization chain for the events.
- Parameters:
roomId
- Required. The room ID to get state for.eventId
- Required. An event ID in the room to retrieve the state at.uriInfo
- Request Information.httpHeaders
- Http headers.asyncResponse
- Asynchronous response.
-
stateIds
@GET @Path("/state_ids/{roomId}") void stateIds(@PathParam("roomId") String roomId, @QueryParam("event_id") String eventId, @Context javax.ws.rs.core.UriInfo uriInfo, @Context javax.ws.rs.core.HttpHeaders httpHeaders, @Suspended javax.ws.rs.container.AsyncResponse asyncResponse)
Retrieves a snapshot of a room's state at a given event, in the form of event IDs. This performs the same function as calling /state/{roomId}, however this returns just the event IDs rather than the full events.
Return:StateIdResponse
.
Requires auth: Yes.Status code 200: The fully resolved state for the room, prior to considering any state changes induced by the requested event. Includes the authorization chain for the events.
- Parameters:
roomId
- Required. The room ID to get state for.eventId
- Required. An event ID in the room to retrieve the state at.uriInfo
- Request Information.httpHeaders
- Http headers.asyncResponse
- Asynchronous response.
-
event
@GET @Path("/event/{eventId}") void event(@PathParam("eventId") String eventId, @Context javax.ws.rs.core.UriInfo uriInfo, @Context javax.ws.rs.core.HttpHeaders httpHeaders, @Suspended javax.ws.rs.container.AsyncResponse asyncResponse)
Retrieves a single event.
Return:PersistedDataUnit
.
Requires auth: Yes.Status code 200: A transaction containing a single PDU which is the event requested.
- Parameters:
eventId
- Required. The event ID to get.uriInfo
- Request Information.httpHeaders
- Http headers.asyncResponse
- Asynchronous response.
-
makeJoin
@GET @Path("/make_join/{roomId}/{userId}") void makeJoin(@PathParam("roomId") String roomId, @PathParam("userId") String userId, @QueryParam("ver") List<String> ver, @Context javax.ws.rs.core.UriInfo uriInfo, @Context javax.ws.rs.core.HttpHeaders httpHeaders, @Suspended javax.ws.rs.container.AsyncResponse asyncResponse)
Asks the receiving server to return information that the sending server will need to prepare a join event to get into the room.
Requires auth: Yes. Return:MakeResponse
.Status code 200: A template to be used for the rest of the Joining Rooms handshake. Note that events have a different format depending on the room version - check the room version specification for precise event formats. The response body here describes the common event fields in more detail and may be missing other required fields for a PDU.
Status code 400: The request is invalid or the room the server is attempting to join has a version that is not listed in the ver parameters. The error should be passed through to clients so that they may give better feedback to users.
- Parameters:
roomId
- Required. The room ID that is about to be joined.userId
- Required. The user ID the join event will be for.ver
- The room versions the sending server has support for. Defaults to [1].uriInfo
- Request Information.httpHeaders
- Http headers.asyncResponse
- Asynchronous response.
-
sendJoin
@PUT @Path("/send_join/{roomId}/{eventId}") void sendJoin(@PathParam("roomId") String roomId, @PathParam("eventId") String eventId, SendRequest request, @Context javax.ws.rs.core.UriInfo uriInfo, @Context javax.ws.rs.core.HttpHeaders httpHeaders, @Suspended javax.ws.rs.container.AsyncResponse asyncResponse)
Submits a signed join event to the resident server for it to accept it into the room's graph. Note that events have a different format depending on the room version - check the room version specification for precise event formats. The request and response body here describes the common event fields in more detail and may be missing other required fields for a PDU.
Requires auth: Yes.
Return: list with status andRoomStateResponse
.Status code 200: The full state for the room, having accepted the join event.
- Parameters:
roomId
- Required. The room ID that is about to be joined.eventId
- Required. The event ID for the join event.request
- Requires. JSON body request.uriInfo
- Request Information.httpHeaders
- Http headers.asyncResponse
- Asynchronous response.
-
invite
@PUT @Path("/invite/{roomId}/{eventId}") void invite(@PathParam("roomId") String roomId, @PathParam("eventId") String eventId, InviteV1Request request, @Context javax.ws.rs.core.UriInfo uriInfo, @Context javax.ws.rs.core.HttpHeaders httpHeaders, @Suspended javax.ws.rs.container.AsyncResponse asyncResponse)
Invites a remote user to a room. Once the event has been signed by both the inviting homeserver and the invited homeserver, it can be sent to all of the servers in the room by the inviting homeserver.
Servers should prefer to use the v2 API for invites instead of the v1 API. Servers which receive a v1 invite request must assume that the room version is either "1" or "2".
Note that events have a different format depending on the room version - check the room version specification for precise event formats. The request and response bodies here describe the common event fields in more detail and may be missing other required fields for a PDU.
Requires auth: Yes.
Return: List of theInteger
andEventContainer
.Status code 200: The event with the invited server's signature added. All other fields of the events should remain untouched. Note that events have a different format depending on the room version - check the room version specification for precise event formats.
Status code 403: The invite is not allowed. This could be for a number of reasons, including:
- The sender is not allowed to send invites to the target user/homeserver.
- The homeserver does not permit anyone to invite its users.
- The homeserver refuses to participate in the room.
- Parameters:
roomId
- Required. The room ID that the user is being invited to.eventId
- Required. The event ID for the invite event, generated by the inviting server.request
- Invite JSON request.uriInfo
- Request Information.httpHeaders
- Http headers.asyncResponse
- Asynchronous response.
-
makeLeave
@GET @Path("/make_leave/{roomId}/{userId}") void makeLeave(@PathParam("roomId") String roomId, @PathParam("userId") String userId, @Context javax.ws.rs.core.UriInfo uriInfo, @Context javax.ws.rs.core.HttpHeaders httpHeaders, @Suspended javax.ws.rs.container.AsyncResponse asyncResponse)
Asks the receiving server to return information that the sending server will need to prepare a leave event to get out of the room.
Requires auth: Yes.
Return: List of theInteger
andMakeResponse
.Status code 200: A template to be used to call /send_leave. Note that events have a different format depending on the room version - check the room version specification for precise event formats. The response body here describes the common event fields in more detail and may be missing other required fields for a PDU.
Status code 403: The request is not authorized. This could mean that the user is not in the room.
- Parameters:
roomId
- Required. The room ID that is about to be left.userId
- Required. The user ID the leave event will be for.uriInfo
- Request Information.httpHeaders
- Http headers.asyncResponse
- Asynchronous response.
-
sendLeave
@PUT @Path("/send_leave/{roomId}/{eventId}") void sendLeave(@PathParam("roomId") String roomId, @PathParam("eventId") String eventId, SendRequest request, @Context javax.ws.rs.core.UriInfo uriInfo, @Context javax.ws.rs.core.HttpHeaders httpHeaders, @Suspended javax.ws.rs.container.AsyncResponse asyncResponse)
Submits a signed leave event to the resident server for it to accept it into the room's graph. Note that events have a different format depending on the room version - check the room version specification for precise event formats. The request and response body here describes the common event fields in more detail and may be missing other required fields for a PDU.
Requires auth: Yes.
Return: List ofInteger
andEmptyResponse
.Status code 200: An empty response to indicate the event was accepted into the graph by the receiving homeserver.
- Parameters:
roomId
- Required. The room ID that is about to be left.eventId
- Required. The event ID for the leave event.request
- JSON body request.uriInfo
- Request Information.httpHeaders
- Http headers.asyncResponse
- Asynchronous response.
-
exchangeThirdPartyInvite
@PUT @Path("/exchange_third_party_invite/{roomId}") void exchangeThirdPartyInvite(@PathParam("roomId") String roomId, ThirdPartyInvite request, @Context javax.ws.rs.core.UriInfo uriInfo, @Context javax.ws.rs.core.HttpHeaders httpHeaders, @Suspended javax.ws.rs.container.AsyncResponse asyncResponse)
The receiving server will verify the partial m.room.member event given in the request body. If valid, the receiving server will issue an invite as per the Inviting to a room section before returning a response to this request.
Requires auth: Yes.
Return:EmptyResponse
.Status code 200: The invite has been issued successfully.
- Parameters:
roomId
- Required. The room ID to exchange a third party invite in.request
- JSON body request.uriInfo
- Request Information.httpHeaders
- Http headers.asyncResponse
- Asynchronous response.
-
onBind
@Path("/3pid/onbind") @Consumes("application/json") @Produces("application/json") void onBind(OnBindRequest onBindRequest, @Context javax.ws.rs.core.UriInfo uriInfo, @Context javax.ws.rs.core.HttpHeaders httpHeaders, @Suspended javax.ws.rs.container.AsyncResponse asyncResponse)
Used by identity servers to notify the homeserver that one of its users has bound a third party identifier successfully, including any pending room invites the identity server has been made aware of. Return:EmptyResponse
.Status code 200: The homeserver has processed the notification.
- Parameters:
onBindRequest
- Request.uriInfo
- Request Information.httpHeaders
- Http headers.asyncResponse
- Asynchronous response.
-
publicRooms
@GET @Path("/publicRooms") void publicRooms(@QueryParam("limit") Integer limit, @QueryParam("since") String since, @QueryParam("include_all_networks") Boolean includeAllNetworks, @QueryParam("third_party_instance_id") String thirdPartyInstanceId, @Context javax.ws.rs.core.UriInfo uriInfo, @Context javax.ws.rs.core.HttpHeaders httpHeaders, @Suspended javax.ws.rs.container.AsyncResponse asyncResponse)
Gets all the public rooms for the homeserver. This should not return rooms that are listed on another homeserver's directory, just those listed on the receiving homeserver's directory.
Requires auth: Yes.
Return:PublicRoomsResponse
.Status code 200: The public room list for the homeserver.
- Parameters:
limit
- The maximum number of rooms to return. Defaults to 0 (no limit).since
- A pagination token from a previous call to this endpoint to fetch more rooms.includeAllNetworks
- Whether or not to include all networks/protocols defined by application services on the homeserver. Defaults to false.thirdPartyInstanceId
- The specific third party network/protocol to request from the homeserver. Can only be used if include_all_networks is false.uriInfo
- Request Information.httpHeaders
- Http headers.asyncResponse
- Asynchronous response.
-
queryDirectory
@GET @Path("/query/directory") void queryDirectory(@QueryParam("room_alias") String roomAlias, @Context javax.ws.rs.core.UriInfo uriInfo, @Context javax.ws.rs.core.HttpHeaders httpHeaders, @Suspended javax.ws.rs.container.AsyncResponse asyncResponse)
Performs a query to get the mapped room ID and list of resident homeservers in the room for a given room alias. Homeservers should only query room aliases that belong to the target server (identified by the DNS Name in the alias).
Servers may wish to cache the response to this query to avoid requesting the information too often.
Requires auth: Yes.
Return:DirectoryResponse
.Status code 200: The corresponding room ID and list of known resident homeservers for the room.
Status code 404: The room alias was not found.
- Parameters:
roomAlias
- Required. The room alias to query.uriInfo
- Request Information.httpHeaders
- Http headers.asyncResponse
- Asynchronous response.
-
queryProfile
@GET @Path("/query/profile") void queryProfile(@QueryParam("user_id") String userId, @QueryParam("field") String field, @Context javax.ws.rs.core.UriInfo uriInfo, @Context javax.ws.rs.core.HttpHeaders httpHeaders, @Suspended javax.ws.rs.container.AsyncResponse asyncResponse)
Performs a query to get profile information, such as a display name or avatar, for a given user. Homeservers should only query profiles for users that belong to the target server (identified by the DNS Name in the user ID).
Servers may wish to cache the response to this query to avoid requesting the information too often.
Requires auth: Yes.
Return:ProfileResponse
.Status code 200: The profile for the user. If a field is specified in the request, only the matching field should be included in the response. If no field was specified, the response should include the fields of the user's profile that can be made public, such as the display name and avatar. If the user does not have a particular field set on their profile, the server should exclude it from the response body or give it the value null.
Status code 404: The user does not exist or does not have a profile.
- Parameters:
userId
- Required. The user ID to query.field
- The field to query. If specified, the server will only return the given field in the response. If not specified, the server will return the full profile for the user. One of: ["displayname", "avatar_url"]uriInfo
- Request Information.httpHeaders
- Http headers.asyncResponse
- Asynchronous response.
-
userInfo
@GET @Path("/openid/userinfo") void userInfo(@QueryParam("access_token") String accessToken, @Context javax.ws.rs.core.UriInfo uriInfo, @Context javax.ws.rs.core.HttpHeaders httpHeaders, @Suspended javax.ws.rs.container.AsyncResponse asyncResponse)
Exchanges an OpenID access token for information about the user who generated the token. Currently this only exposes the Matrix User ID of the owner.
Return:UserInfoResponse
.Status code 200: Information about the user who generated the OpenID access token.
Status code 401: The token was not recognized or has expired.
- Parameters:
accessToken
- Required. The OpenID access token to get information about the owner for.uriInfo
- Request Information.httpHeaders
- http headers.asyncResponse
- Asynchronous response.
-
userDevices
@GET @Path("/user/devices/{userId}") void userDevices(@PathParam("userId") String userId, @Context javax.ws.rs.core.UriInfo uriInfo, @Context javax.ws.rs.core.HttpHeaders httpHeaders, @Suspended javax.ws.rs.container.AsyncResponse asyncResponse)
Gets information on all of the user's devices.
Requires auth: Yes.
Return:DeviceResponse
.Status code 200: The user's devices.
- Parameters:
userId
- Required. The user ID to retrieve devices for. Must be a user local to the receiving homeserver.uriInfo
- Request Information.httpHeaders
- Http headers.asyncResponse
- Asynchronous response.
-
userKeysClaim
@POST @Path("/user/keys/claim") void userKeysClaim(KeyClaimRequest request, @Context javax.ws.rs.core.UriInfo uriInfo, @Context javax.ws.rs.core.HttpHeaders httpHeaders, @Suspended javax.ws.rs.container.AsyncResponse asyncResponse)
Claims one-time keys for use in pre-key messages.
Requires auth: Yes.
Return:Map
of user ID toMap
from devices to aMap
from <algorithm>:<key_id> to key object.Status code 200: The claimed keys.
- Parameters:
request
- Required. The keys to be claimed. A map from user ID, to a map from device ID to algorithm name.uriInfo
- Request Information.httpHeaders
- Http headers.asyncResponse
- Asynchronous response.
-
userKeysQuery
@POST @Path("/user/keys/query") void userKeysQuery(KeyQueryRequest request, @Context javax.ws.rs.core.UriInfo uriInfo, @Context javax.ws.rs.core.HttpHeaders httpHeaders, @Suspended javax.ws.rs.container.AsyncResponse asyncResponse)
Returns the current devices and identity keys for the given users.
Requires auth: Yes.
Return:KeyQueryResponse
.Status code 200: The device information.
- Parameters:
request
- JSON request.uriInfo
- Request Information.httpHeaders
- Http headers.asyncResponse
- Asynchronous response.
-
-


My LA Trip
Photo #1
This picture was taken on Sunset Avenue. It was just before sunset and the palm trees looked really pretty with the background color.
Photo #2
This second photo was also taken on the same day as the first one, also on Sunset Avenue. I thought it had a good sense of displaying the general chill vibe of Los Angelos, which was pretty cool and relaxing.
Photo #3
This one was taken on Santa Monica beach and it was also about to get darl. We saw the sunset on the beach and the sky looked so pretty with mixed colors of blue and pink. There was also a little part of the city shown in this image and that contributes to the general looking of the photo also.


Welcome {{worklist.user.name}}
Nominate people to submit feedback or provide ad-hoc feedback for a colleague.
No pending actions


Preparation time
less than 30 mins
Cooking time
30 mins to 1 hour
Serves
Serves 4
A lovely simple way to cook cod! Plenty of flavour from the sweet roasted veg and the crunchy cheesy breadcrumbs.
Preheat the oven to 200C/180C Fan/Gas 6.
Put the peppers, courgettes and onion on a large baking tray and drizzle with oil. Season with salt and pepper and toss everything together until the vegetables are lightly coated. Roast for 20 minutes until softened and lightly charred.
Pat dry the fish on kitchen paper and check for any bones. Remove any that you see with tweezers. Season the fish with black pepper and wrap each fillet loosely with a slice of ham.
Remove the tray and make gaps for the fish. Place the fish on the tray. Mix the breadcrumbs with the Parmesan and parsley and scatter over the fish and vegetables.
Bake for another 12–15 minutes or until the fish is cooked, the ham has crisped and the breadcrumbs are lightly browned.
Meanwhile, to cook the spinach, heat a medium sauté pan and add the butter. Once melted add the spinach and cook for a minute or so until wilted.
Serve the cod hot, drizzled with a little balsamic vinegar, on a bed of wilted spinach.


Full-Stack Inventory Managment System. Created to help "Fresh Time" Food Market keep track of there produce, and expiration dates. There old system was with pen and paper.
Java | JavaScript | Html/CSS | H2 Database | Spring Boot
A simple Calculator created with Javascript Framework Vue.
Vue | JavaScript | Html/CSS
First Full-Stack Java Web application. A simple Book Review app that alows the user to add tags to describe the books and also leave comments.
Spring | Java | Html | TDD
Mastering the Art of OOP, with the help of Tamagotchi-like Virtual Pets. Explore all the charm of the lovable 90s toy with fun new custom pets. Use your own names to add a personal touch to your lovable pets so they are more
memorable as they die.
OOP | Java | TDD
Simple Temp conversion form Celsius to Fahrenheit, or Fahrenheit to Celsius.
Java
TacticAS, a board game for Champions. Command a team of Units. Equip them as you see fit, and do battle against your friends. 2-4 players. This game is similar to HeroClix or MageKnight. It is a minitures game all in one box with one affordable price
and half the hassle. Still some hassle though.
Photoshop/Gimp
Professional cat owner. It takes a lot to own one of these creatures. I've successfully kept this small beast alive for about a year now. The struggle is real. She barely cares about me. One time this deviant ruined a rug within 24hrs of buying it
by throwing up on it.
Willpower | Diligence | Determination


ECIL distributes 900 satchels, water bottles to ZPHS students
Activity was part of its corporate social responsibility
by Staff ReporterElectronics Corporation of India Limited (ECIL), as part of its corporate social responsibility, distributed 900 bags and an equal number of water bottles at the Zilla Parishad High Schools (ZPHS) for boys and girls in Malkajgiri.
The event was organised at the ZPHS (boys) where Swarna Sankaran, executive director (Finance), handed over the bags and water bottles.
Addressing the students, Ms Sankaran urged them to take up a sport to keep themselves physically and mentally fit.
They were also advised to pay attention to current affairs to help them prepare for competitive examinations.
A statement released to the media stated that in the past five years, the ECIL has provided school infrastructure to several government schools in places like Keesara, Kapra, Alwal and Malkajgiri.


| type | apiKey | |
|---|---|---|
| name | api_key | |
| in | HEADER |
| type | basic |
|---|
| type | oauth2 | |
|---|---|---|
| authorizationUrl | http://swagger.io/api/oauth/dialog | |
| flow | implicit | |
| scopes | write:pets | modify pets in your account |
| read:pets | read your pets | |
| Name | Located in | Required | Description | Default | Schema |
|---|---|---|---|---|---|
| startId | query | yes | start ID of pets that need to be fetched | - | integer (int64) |
| endId | query | yes | end ID of pets that need to be fetched | - | integer (int64) |
| Name | Located in | Required | Description | Default | Schema |
|---|---|---|---|---|---|
| body | body | yes | Pet object that needs to be added to the store | - | Pet |
| Name | Located in | Required | Description | Default | Schema |
|---|---|---|---|---|---|
| body | body | yes | Pet object that needs to be added to the store | - | Pet |
| Name | Located in | Required | Description | Default | Schema |
|---|---|---|---|---|---|
| status | query | yes | Status values that need to be considered for filter | - | Array[string] (multi) |
| Name | Located in | Required | Description | Default | Schema |
|---|---|---|---|---|---|
| tags | query | yes | Tags to filter by | - | Array[string] (multi) |
| Name | Located in | Required | Description | Default | Schema |
|---|---|---|---|---|---|
| petName | path | yes | petName (**Pattern**: `[^/]*`) | - | string |
| Name | Located in | Required | Description | Default | Schema |
|---|---|---|---|---|---|
| pet | query | no | describe Pet in json here | - | string |
| Name | Located in | Required | Description | Default | Schema |
|---|---|---|---|---|---|
| header-test-name | header | yes | header-test-value | - | string |
| path-test-name | path | yes | path-test-value | - | string |
| body-test-name | body | yes | body-test-value | - | Pet |
| Name | Located in | Required | Description | Default | Schema |
|---|---|---|---|---|---|
| form-test-name | formData | yes | form-test-value | - | Array[string] (multi) |
| Name | Located in | Required | Description | Default | Schema |
|---|---|---|---|---|---|
| petId | path | yes | ID of pet that needs to be fetched (**Pattern**: `[0-9]`) | - | integer (int64) |
| Name | Located in | Required | Description | Default | Schema |
|---|---|---|---|---|---|
| petId | path | yes | ID of pet that needs to be updated | - | string |
| name | formData | no | Updated name of the pet | - | string |
| status | formData | no | Updated status of the pet | - | string |
| myHeader | header | no | - | string | |
| intValue | header | no | - | integer (int32) | |
| listValue | query | no | - | Array[string] (multi) | |
| myParentHeader | header | no | Header from parent | - | string |
| Name | Located in | Required | Description | Default | Schema |
|---|---|---|---|---|---|
| api_key | header | no | - | string | |
| petId | path | yes | Pet id to delete | - | integer (int64) |
| Name | Located in | Required | Description | Default | Schema |
|---|---|---|---|---|---|
| petId | path | yes | ID of pet that needs to be updated | - | string |
| name | formData | no | Updated name of the pet | - | string |
| status | formData | no | Updated status of the pet | - | string |
| myHeader | header | no | - | string | |
| intValue | header | no | - | integer (int32) | |
| listValue | query | no | - | Array[string] (multi) | |
| myParentHeader | header | no | Header from parent | - | string |
| Name | Located in | Required | Description | Default | Schema |
|---|---|---|---|---|---|
| startId | path | yes | start ID of pets that need to be fetched (**Pattern**: `[0-9]{1,2}`) | - | integer (int64) |
| endId | path | yes | end ID of pets that need to be fetched (**Pattern**: `[0-9]{1,2}`) | - | integer (int64) |
| Name | Located in | Required | Description | Default | Schema |
|---|---|---|---|---|---|
| body | body | yes | order placed for purchasing the pet | - | Order |
| Name | Located in | Required | Description | Default | Schema |
|---|---|---|---|---|---|
| orderId | path | yes | ID of pet that needs to be fetched | - | string |
| Name | Located in | Required | Description | Default | Schema |
|---|---|---|---|---|---|
| orderId | path | yes | ID of the order that needs to be deleted | - | string |
| Name | Located in | Required | Description | Default | Schema |
|---|---|---|---|---|---|
| orderIds | path | yes | IDs of pets that needs to be fetched | - | Array[string] (csv) |
| Name | Located in | Required | Description | Default | Schema |
|---|---|---|---|---|---|
| body | body | yes | Created user object | - | User |
| Name | Located in | Required | Description | Default | Schema |
|---|---|---|---|---|---|
| body | body | yes | List of user object | - | Array[User] |
| Name | Located in | Required | Description | Default | Schema |
|---|---|---|---|---|---|
| body | body | yes | List of user object | - | Array[User] |
| Name | Located in | Required | Description | Default | Schema |
|---|---|---|---|---|---|
| username | query | yes | The user name for login | - | string |
| password | query | yes | The password for login in clear text | - | string |
| Name | Located in | Required | Description | Default | Schema |
|---|---|---|---|---|---|
| username | path | yes | The name that needs to be fetched. Use user1 for testing. | - | string |
| Name | Located in | Required | Description | Default | Schema |
|---|---|---|---|---|---|
| username | path | yes | name that need to be deleted | - | string |
| body | body | yes | Updated user object | - | User |
| Name | Located in | Required | Description | Default | Schema |
|---|---|---|---|---|---|
| username | path | yes | The name that needs to be deleted | - | string |
| name | type | required | description | example |
|---|---|---|---|---|
| id | integer (int64) | optional | - | |
| name | string | optional | - |
| name | type | required | description | example |
|---|---|---|---|---|
| id | integer (int64) | optional | - | |
| petId | integer (int64) | optional | - | |
| quantity | integer (int32) | optional | - | |
| shipDate | string (date-time) | optional | - | |
| status | string | optional | Order Status | |
| complete | boolean | optional | - | |
| optionalStatus | string | optional | - |
| name | type | required | description | example |
|---|---|---|---|---|
| id | integer | optional | - | |
| category | Category | optional | - | |
| name | string | required | - | doggie |
| photoUrls | array[string] | required | - | |
| tags | array[Tag] | optional | - | |
| status | string | optional | pet status in the store |
| name | type | required | description | example |
|---|---|---|---|---|
| id | integer (int64) | optional | - | |
| name | string | optional | - |
| name | type | required | description | example |
|---|---|---|---|---|
| id | integer (int64) | optional | - | |
| username | string | optional | - | |
| firstName | string | optional | - | |
| lastName | string | optional | - | |
| string | optional | - | ||
| password | string | optional | - | |
| phone | string | optional | - | |
| userStatus | integer (int32) | optional | User Status | 2 |


We scraped the text of each webpage contained in the web corpus built in the previous phase. The resulting documents kept the categorization of the original web pages and was therefore organized into three groups:
In order to have as much clean content as possible we applied BOILERPIPE, an algorithm used to detect and remove the surplus "clutter" (boilerplate, templates) around the main textual content of a web page.
Kohlschütter, Christian, Peter Fankhauser, and Wolfgang Nejdl. "Boilerplate detection using shallow text features." Proceedings of the third ACM international conference on Web search and data mining. ACM, 2010.We processed the text corpus using some natural language processing techniques as fast part-of-speech tagger (identification of nouns, adjectives, verbs, etc. in a sentence) and n-grams extractor. For each extracted entity we calculated its Term Frequency (TF) and its term frequency–inverse document frequency (TF-IDF), performed along the three categories of documents. We also excluded some overly generic entities and we used stop-word lists. For this phase we used SVEN, a software developed at DensityDesign | Politecnico di Milano and médialab | SciencesPo, that implement Pattern a text mining library developed at CLiPS | University of Antwerp.
De Smedt, Tom, and Walter Daelemans. "Pattern for python." The Journal of Machine Learning Research 98888 (2012): 2063-2067.The resulting n-grams have been visualized with a slopegraph model that allow to make several visual comparisons along the different categories of documents. All vertical lists in the diagram contain the same n-grams, thus highlighting the hierarchy of n-grams in the different categories and the specific number of occurrences associated to them, as well as the changing configuration when comparing TF and TFIDF n-grams.


Welcome to Pei-yuan's blog
Apart from studying for my curriculum coursework, I also spend time reading literatures and histories in my spare time. I play many sports as well, basketball, badminton, and table tennis. Especially, I had the experience of playing for high school flag-football team; I was also a part of the running team for junior and senior high schools. Moreover, I love travelling and have already visited a lot of places. I have been to 20 provinces in China, 15 states in United state, and 3 countries of the world. I like to learn about the culture and history of cities that I visit. I normally would walk along the main stree of the downtown to feel and enjoy the cultural ambience, taste delicious and special food, and visit all famous and worthgoing places.
Xiangyang - My First Home
I was born in Xiangyang (/Hs'iang yang/) (襄阳), used to be called Xiang Fan，in Hubei province. I lived in Xiangyang for about 9 years. It holds my whole precious childhood memories. I really crave to live for some years in Xiangyang in future after completing my study.
XiangFan is an integration of two ancient cities: Xiangyang （襄阳） and Fancheng(樊城). The name was changed to Xiangyang, probably for attracting tourists. Xiangyang is a famous townthroughout the history because it is right on the "border line" that divides not only south and north, but also east and west. This "border line" is meaningful, because it partitions climates, landscapes, and even cultures. Moreover, its specific features also contribute to its importance in the war. It is the inevitable city to be conquered in all civil wars of through Chinese history.
It is also known among people because of Luo Guanzhong (罗贯中)'s novel, Romance of Three Kingdoms and Zhuge Kongming. (诸葛亮/诸葛孔明）The place, where Zhuge kongming lives when he farms, Crouching Dragon (卧龙岗), is located in Xiangyang. Now, it is famous because it is a main city in Louis Cha(金庸) ‘s novel, The Romance of the Condor Heroes (神雕侠侣).
Xiangyang is the "center" of China. From this beautiful section of Google map, every one can feel it (The location of Xiangyang).
Xiangyang is an awesome place to visit.
citation: Tangcheng (唐城)- http://jingchu.baike.com/article-842833.html
Beijing - My Second Home
I moved to Beijing when I was 9, with my family. I loved "Beijing" as well. It is the place for me to level up my horizon and knoweldge. The most fascinating thing is that it is also an ancient city, full of histories and cultures.
I had lived in Peiyuan for 9 years as well, before I came to the US for college. I indeed appreciate my parents for the ideal living and studying environment they created. I was accepted in a top middle school in Dongcheng (东城) district and went to High School Attached to Tsinghua University （清华大学附属中学） thereafter.
If you plan to visit Beijing, I would be happy to become your tour guide. I really enjoy travelling, and therefore I know all kinds of fun places here in Beijing, including ancient spots, museums, parks, and even shopping marts.
Even picutres of common sites in Beijing are beautiful, Aren't they?


Hello, I'm Alam. I work as a security engineer. I like building command line interfaces. My main interests are containers, kubernetes and go.
The goal of this blog is to serve as notes for my future self, and useful notes for others.
This site is built using go and deployed as a serverless app. This post describes the technology behind it. If you discover any problems with the content, please create an issue on the github repo.
Please feel free to reach me via email or LinkedIn if you have questions or feedback.


Download and read raw data¶
Download¶
Before you download data, make sure that you specific the pass to the raw data directory (rawdir
) in ninolearn.pathes
.
In this tutorial, we download the monthly Oceaninc Nino Index, the Warm Water Volume (WWV), the dipole mode index (DMI) of the Indian ocean dipole (IOD) and sea surface temparatures from the ERSSTv5 data set and sea surface heights from the ORAS4 data set.
[1]:
# import the necessary methods and classes
from ninolearn.download import download, sources
NOTE: If the data was already downloaded, it won’t be downloaded again.
[8]:
download(sources.SST_ERSSTv5)
download(sources.ONI)
download(sources.IOD)
download(sources.WWV)
download(sources.SAT_monthly_NCEP)
sst.mnmean.nc already downloaded
oni.txt already downloaded
iod.txt already downloaded
wwv.dat already downloaded
Download air.mon.mean.nc
The sources all are dictionaries which have keywords that specify the download:
[3]:
print(sources.SST_ERSSTv5)
{'downloadType': 'ftp', 'filename': 'sst.mnmean.nc', 'host': 'ftp.cdc.noaa.gov', 'location': '/Datasets/noaa.ersst.v5/'}
[4]:
print(sources.ONI)
{'downloadType': 'http', 'url': 'https://www.cpc.ncep.noaa.gov/data/indices/oni.ascii.txt', 'filename': 'oni.txt'}
You can see that that the two sources above have entries different downloadTypes. The SST is downloaded from an ftp-server, whereas the ONI is downloaded via http.
Read raw data¶
Routines are available in the ninolearn.IO.read_raw
module with which it is directly possible to read the raw data as it is.
[10]:
from ninolearn.IO.read_raw import oni, sst_ERSSTv5, sat, wwv_anom, iod
ONI = oni()
SST = sst_ERSSTv5()
SAT = sat(mean='monthly')
WWV = wwv_anom()
Let’s have a look how the raw data looks like!
[11]:
ONI.head()
[11]:
| SEAS | YR | TOTAL | ANOM | |
|---|---|---|---|---|
| 0 | DJF | 1950 | 24.72 | -1.53 |
| 1 | JFM | 1950 | 25.17 | -1.34 |
| 2 | FMA | 1950 | 25.75 | -1.16 |
| 3 | MAM | 1950 | 26.12 | -1.18 |
| 4 | AMJ | 1950 | 26.32 | -1.07 |
[5]:
WWV.head()
[5]:
| date | Volume | Anomaly | |
|---|---|---|---|
| 0 | 198001 | 2.605404e+15 | 7.657363e+13 |
| 1 | 198002 | 2.564434e+15 | 7.004931e+13 |
| 2 | 198003 | 2.514065e+15 | 5.240853e+13 |
| 3 | 198004 | 2.468250e+15 | 4.008869e+13 |
| 4 | 198005 | 2.439852e+15 | 4.020975e+13 |
[20]:
print(SST)
<xarray.DataArray 'sst' (time: 1982, lat: 89, lon: 180)>
[31751640 values with dtype=float32]
Coordinates:
* lat (lat) float32 88.0 86.0 84.0 82.0 80.0 ... -82.0 -84.0 -86.0 -88.0
* lon (lon) float32 0.0 2.0 4.0 6.0 8.0 ... 350.0 352.0 354.0 356.0 358.0
* time (time) datetime64[ns] 1854-01-01 1854-02-01 ... 2019-02-01
Attributes:
long_name: Monthly Means of Sea Surface Temperature
units: degC
var_desc: Sea Surface Temperature
level_desc: Surface
statistic: Mean
dataset: ERSSTv5
parent_stat: Individual Values
actual_range: [-1.8 42.32636]
valid_range: [-1.8 45. ]
[21]:
print(SAT)
<xarray.DataArray 'air' (time: 854, lat: 73, lon: 144)>
[8977248 values with dtype=float32]
Coordinates:
* lat (lat) float32 90.0 87.5 85.0 82.5 80.0 ... -82.5 -85.0 -87.5 -90.0
* lon (lon) float32 0.0 2.5 5.0 7.5 10.0 ... 350.0 352.5 355.0 357.5
* time (time) datetime64[ns] 1948-01-01 1948-02-01 ... 2019-02-01
Attributes:
long_name: Monthly Mean Air Temperature at sigma level 0.995
valid_range: [-2000. 2000.]
units: degC
precision: 1
var_desc: Air Temperature
level_desc: Surface
statistic: Mean
parent_stat: Individual Obs
dataset: NCEP
actual_range: [-73.78001 42.14595]
As you can see, the data sets do not have a common time axis, are available for different time periods and on different grids.
To bring the different data sets onto a common/standardized shape, check out the tutorials on preparing the data and postprocessing it.


We are Information, Counselling and Legal Assistance(ICLA) group of Norwegian Refugee Council(NRC).
Indentity registeration, Possession documents, Human rights information, information about institutions and counselling of other legal matters.
What does this team member to? Keep it short! This is also a great spot for social links!
What does this team member to? Keep it short! This is also a great spot for social links!
What does this team member to? Keep it short! This is also a great spot for social links!
What does this team member to? Keep it short! This is also a great spot for social links!
What does this team member to? Keep it short! This is also a great spot for social links!


The Jest watch plugin system provides a way to hook into specific parts of Jest and to define watch mode menu prompts that execute code on key press. Combined, these features allow you to develop interactive experiences custom for your workflow.
class MyWatchPlugin {
// Add hooks to Jest lifecycle events
apply(jestHooks) {}
// Get the prompt information for interactive plugins
getUsageInfo(globalConfig) {}
// Executed when the key from `getUsageInfo` is input
run(globalConfig, updateConfigAndRun) {}
}
To connect your watch plugin to Jest, add its path under watchPlugins
in your Jest configuration:
Custom watch plugins can add hooks to Jest events. These hooks can be added either with or without having an interactive key in the watch mode menu.
apply(jestHooks)
Jest hooks can be attached by implementing the apply
method. This method receives a jestHooks
argument that allows the plugin to hook into specific parts of the lifecycle of a test run.
Below are the hooks available in Jest.
jestHooks.shouldRunTestSuite(testPath)
Returns a boolean (or Promise<boolean>
for handling asynchronous operations) to specify if a test should be run or not.
For example:
class MyWatchPlugin {
apply(jestHooks) {
jestHooks.shouldRunTestSuite((testPath) => {
return testPath.includes('my-keyword');
});
// or a promise
jestHooks.shouldRunTestSuite((testPath) => {
return Promise.resolve(testPath.includes('my-keyword'));
});
}
}
jestHooks.onTestRunComplete(results)
Gets called at the end of every test run. It has the test results as an argument.
For example:
class MyWatchPlugin {
apply(jestHooks) {
jestHooks.onTestRunComplete((results) => {
this._hasSnapshotFailure = results.snapshot.failure;
});
}
}
jestHooks.onFileChange({projects})
Gets called whenever there is a change in the file system
projects: Array<config: ProjectConfig, testPaths: Array<string>
: Includes all the test paths that Jest is watching.For example:
class MyWatchPlugin {
apply(jestHooks) {
jestHooks.onFileChange(({projects}) => {
this._projects = projects;
});
}
}
Custom watch plugins can also add or override functionality to the watch menu by specifying a key/prompt pair in getUsageInfo
method and a run
method for the execution of the key.
getUsageInfo(globalConfig)
To add a key to the watch menu, implement the getUsageInfo
method, returning a key and the prompt:
class MyWatchPlugin {
getUsageInfo(globalConfig) {
return {
key: 's',
prompt: 'do something',
};
}
}
This will add a line in the watch mode menu (› Press s to do something.
)
Watch Usage
› Press p to filter by a filename regex pattern.
› Press t to filter by a test name regex pattern.
› Press q to quit watch mode.
› Press s to do something. // <-- This is our plugin
› Press Enter to trigger a test run.
Note: If the key for your plugin already exists as a default key, your plugin will override that key.
run(globalConfig, updateConfigAndRun)
To handle key press events from the key returned by getUsageInfo
, you can implement the run
method. This method returns a Promise<boolean>
that can be resolved when the plugin wants to return control to Jest. The boolean
specifies if Jest should rerun the tests after it gets the control back.
globalConfig
: A representation of Jest’s current global configurationupdateConfigAndRun
: Allows you to trigger a test run while the interactive plugin is running.Note: If you do call updateConfigAndRun
, your run
method should not resolve to a truthy value, as that would trigger a double-run.
For stability and safety reasons, only part of the global configuration keys can be updated with updateConfigAndRun
. The current white list is as follows:
bail
changedSince
collectCoverage
collectCoverageFrom
collectCoverageOnlyFrom
coverageDirectory
coverageReporters
notify
notifyMode
onlyFailures
reporters
testNamePattern
testPathPattern
updateSnapshot
verbose
Plugins can be customized via your Jest configuration.
// jest.config.js
module.exports = {
// ...
watchPlugins: [
[
'path/to/yourWatchPlugin',
{
key: 'k', // <- your custom key
prompt: 'show a custom prompt',
},
],
],
};
Recommended config names:
key
: Modifies the plugin key.prompt
: Allows user to customize the text in the plugin prompt.If the user provided a custom configuration, it will be passed as an argument to the plugin constructor.
Jest allows third-party plugins to override some of its built-in feature keys, but not all. Specifically, the following keys are not overwritable :
c
(clears filter patterns)i
(updates non-matching snapshots interactively)q
(quits)u
(updates all non-matching snapshots)w
(displays watch mode usage / available actions)The following keys for built-in functionality can be overwritten :
p
(test filename pattern)t
(test name pattern)Any key not used by built-in functionality can be claimed, as you would expect. Try to avoid using keys that are difficult to obtain on various keyboards (e.g. é
, €
), or not visible by default (e.g. many Mac keyboards do not have visual hints for characters such as |
, \
, [
, etc.)
Should your plugin attempt to overwrite a reserved key, Jest will error out with a descriptive message, something like:
Watch plugin YourFaultyPlugin attempted to register key
, that is reserved internally for quitting watch mode. Please change the configuration key for this plugin.
Third-party plugins are also forbidden to overwrite a key reserved already by another third-party plugin present earlier in the configured plugins list (watchPlugins
array setting). When this happens, you’ll also get an error message that tries to help you fix that:
Watch plugins YourFaultyPlugin and TheirFaultyPlugin both attempted to register key
. Please change the key configuration for one of the conflicting plugins to avoid overlap.