Package com.postman.collection

Class Collection

java.lang.Object

com.postman.collection.CollectionElement

com.postman.collection.Item

com.postman.collection.ItemGroup

com.postman.collection.Collection

public class Collection
extends ItemGroup

Encapsulates a Postman collection

Postman SDK analog: Collection

Ingest a collection file

Collection myCollection = pmcFactory(new File("example-cat-facts-with-tests.postman_collection.json");

Ingest a collection from Postman

  PostmanID myID = new PostmanID("invalid input: '&#60'your-collection-idinvalid input: '&#62'"); 
  Collection myCollection = Collection.pmcFactory(myID);
 

Get a request item

Item myReq = myCollection.getItem("Get Random Fact");

Get pre-request script for the request

Event preReq = myReq.getPreRequestScript();

Get source code for pre-request script

String myCode = preReq.getSourceCode();

Constructor Summary

Constructors

Constructor	Description
Collection(String name)	Construct a new, empty collection with the specified name

Method Summary

Modifier and Type	Method	Description
void	addCollection(Collection newColl)	Add another collection and it's array of item, variable, and event arrays to this collection in a new Folder.
void	addCollection(Collection newColl, boolean copyScripts, boolean copyVariables)	Add another collection and it's array of item, optionally variable, and optionally event arrays to this collection as children of a new Folder child item of this collection.
void	addCollection(Collection newColl, ItemGroup parent)	Add another collection and it's array of item, variable, and event arrays to this collection as children of parent
void	addCollection(Collection newColl, ItemGroup parent, boolean copyScripts, boolean copyVariables)	Add another collection and it's array of item, optionally variable, and optionally event arrays to this collection as children of the specified parent.
Folder	addFolder(String name)	Convenience method to add an item with no child items to this collection.
Folder	addFolder(String name, int index)	Convenience method to add an item with no child items to this collection.
Request	addRequest(RequestBody reqElement, String name)	Convenience method to add a new request item as a top level child item of this collection
Request	addRequest(RequestBody reqElement, String name, int position)	Add a new request to this collection at the specified position in the array of request elements
Request	addRequest(RequestBody reqElement, String name, Response response)	Create and add a new request as a top level child item of this collection.
Request	addRequest(RequestBody newRequest, String name, ArrayList<Response> responses)	Convenience method to add a request with a pre-constructed ArrayList<Response> of response items.
Request	addRequest(String url)	Create and add a new request as a top level child item of this collection.
void	addVariable(Property varNew)	Add or replace variable to the collection of variables comprising this collections variable array property.
void	addVariables(PropertyList<Property> newVars)
RequestAuth	getAuth()	Return the values in the auth object property of this collection, or null if it has not been set.
String	getDescription()	Return the value of the description property
Map<String,String>	getInfo()	Return a Map<String> containing the key-value pairs comprising the info object property of this collection.
String	getKey()
String	getName()
String	getPostmanID()	Return the _postman_id property of the info object property of this collection
Request	getRequest(String name)	Return a request from this Collections item property, or null if it doesn't exist.
Property	getVariable(String key)	Return the Property key-value pair from this collection's variable array element, or null if it is not present.
PropertyList<Property>	getVariables()	Get the ArrayList<Property> containing the key-value pairs comprising the variable array element of this collection
void	moveItem(Item itemToMove, ItemGroup newParent)	Move an item to a different parent item.
void	moveItem(String itemToMoveKey, String parentKey)	Moves an item in the array of items contained by this collection from one parent to another.
static Collection	pmcFactory()	Static factory method to create the new collection.
static Collection	pmcFactory(PostmanID id)
static Collection	pmcFactory(File jsonFile)	Static factory method to create a new Collection from a Postman collection JSON file.
static Collection	pmcFactory(String json)
static Collection	pmcFactory(URL collectionURL)	Create a collection via the Postman API
void	removeVariable(Property varNew)	Remove variable from the array of key-value pairs comprising this collections variable array element.
void	removeVariable(String key)	Remove variable with the specified key from the array of key-value pairs comprising this collections variable array element.
String	resolveVariables(String src)
void	setAuth(RequestAuth auth)	Set the auth object property of this collection with a RequestAuth object containing the values.
void	setDescription(String desc)	Set the value of the description property
void	setExporterID(String id)	Set the _exporter_id property of the info object property of this collection
void	setInfo(String name, String description, String postmanID, String exporterID, String schemaURI)	set all elements of the info property object of this collection.
void	setInfo(HashMap<String,String> newInfo)	Set the value of this collections info object property with a populated Hash<String> containing the key-value pairs.
void	setName(String newName)
void	setPostmanID(String id)	Set the _postman_id property of the info object property of this collection
void	setSchemaURI(URI schemaURI)	Set the schema property of the info object property of this collection
void	setVariables(PropertyList<Property> vars)	Set the array of key-value pairs in this collections variable array element
String	toJson()	Generate JSON as text from the values in this collection.
PostmanID	upsertToPostman()
PostmanID	upsertToPostman(PostmanID workspaceID)	Create or update this collection in Postman.
void	writeToFile(File outputFile)	Write this collections generated JSON to a file at the specified path.

Methods inherited from class com.postman.collection.ItemGroup

addItem, addItem, addItems, getFolder, getItem, getItem, getItems, getItems, hasItem, removeItem, removeItem, setItems

Methods inherited from class com.postman.collection.Item

getEvent, getEvents, getParent, getPreRequestScript, getTestScript, setEvents, setParent, setPreRequestScript, setTestScript

Methods inherited from class com.postman.collection.CollectionElement

getCollection, getDefaultCollectionSchema, getDefaultValidationSchema, getUUID, getValidationMessages, isEquivalentTo, setParent, setUUID, toJson, validate, validate

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Collection

public Collection(String name)

Construct a new, empty collection with the specified name

Method Details

moveItem

public void moveItem(String itemToMoveKey,
 String parentKey)
              throws RecursiveItemAddException,
InvalidCollectionActionException

Moves an item in the array of items contained by this collection from one parent to another.

Parameters:

itemToMoveKey -

parentKey -

Throws:

InvalidCollectionActionException - If either the parent or item to be moved aren't present in the item array

RecursiveItemAddException

addFolder

public Folder addFolder(String name)
                 throws RecursiveItemAddException,
IllegalPropertyAccessException

Convenience method to add an item with no child items to this collection.

Parameters:

name - The name for the new item

Throws:

RecursiveItemAddException

IllegalPropertyAccessException

addFolder

public Folder addFolder(String name,
 int index)
                 throws RecursiveItemAddException,
IllegalPropertyAccessException

Convenience method to add an item with no child items to this collection.

Parameters:

name - The name for the new item

Throws:

RecursiveItemAddException

IllegalPropertyAccessException

addRequest

public Request addRequest(RequestBody reqElement,
 String name,
 Response response)
                   throws RecursiveItemAddException,
IllegalPropertyAccessException

Create and add a new request as a top level child item of this collection.

Parameters:

newRequest - The new request to add

name - The name for the new item

response - A response to include in the request item, or null to ignore

Returns:

Item The new Request item

Throws:

RecursiveItemAddException - If this collection already include this instance in it's array of items.

IllegalPropertyAccessException

addRequest

public Request addRequest(String url)
                   throws RecursiveItemAddException,
IllegalPropertyAccessException,
InvalidCollectionActionException,
DuplicateVariableKeyException

Create and add a new request as a top level child item of this collection. The request will be named 'New Request'

Parameters:

url - The URL for the request. Cannot be null or non-zero

Returns:

Item The new Request item

Throws:

RecursiveItemAddException - If this collection already include this instance in it's array of items.

DuplicateVariableKeyException - If parsing the URL results in the creation of duplicate parameter variables.

IllegalPropertyAccessException

InvalidCollectionActionExample - If a null or zero-length string URL is passed.

InvalidCollectionActionException

addRequest

public Request addRequest(RequestBody reqElement,
 String name)
                   throws RecursiveItemAddException,
IllegalPropertyAccessException

Convenience method to add a new request item as a top level child item of this collection

Parameters:

reqElement -

name -

Returns:

Item

Throws:

RecursiveItemAddException - If this collection already include this instance in it's array of items.

IllegalPropertyAccessException

getRequest

public Request getRequest(String name)

Return a request from this Collections item property, or null if it doesn't exist.

Overrides:

getRequest in class ItemGroup

addRequest

public Request addRequest(RequestBody newRequest,
 String name,
 ArrayList<Response> responses)
                   throws RecursiveItemAddException,
IllegalPropertyAccessException

Convenience method to add a request with a pre-constructed ArrayList<Response> of response items.

Parameters:

newRequest - The new Request to add

name - The name of the request

responses - Pre-constructed ArrayList of response objects.

Returns:

Item The new request item.

Throws:

RecursiveItemAddException - If this collection already include this instance in it's array of items.

IllegalPropertyAccessException

addRequest

public Request addRequest(RequestBody reqElement,
 String name,
 int position)
                   throws RecursiveItemAddException,
IllegalPropertyAccessException

Add a new request to this collection at the specified position in the array of request elements

Parameters:

reqElement -

name -

position -

Throws:

RecursiveItemAddException - If this collection already include this instance in it's array of items.

IllegalPropertyAccessException

moveItem

public void moveItem(Item itemToMove,
 ItemGroup newParent)
              throws RecursiveItemAddException,
InvalidCollectionActionException

Move an item to a different parent item.

Parameters:

itemToMove - The item to move

newParent - The item's new parent

Throws:

RecursiveItemAddException - If the parent item is the same as the new child item, or if the parent item already contains this item.

InvalidCollectionActionException

addCollection

public void addCollection(Collection newColl,
 ItemGroup parent)
                   throws RecursiveItemAddException,
InvalidCollectionActionException,
IllegalPropertyAccessException

Add another collection and it's array of item, variable, and event arrays to this collection as children of parent

Parameters:

newColl - The collection to combine with this one

parent -

Throws:

RecursiveItemAddException - If the new collection is the same as this collection

InvalidCollectionActionException - If the specified parent is not a folder (e.g., contains a request element)

IllegalPropertyAccessException

addCollection

public void addCollection(Collection newColl,
 boolean copyScripts,
 boolean copyVariables)
                   throws RecursiveItemAddException,
InvalidCollectionActionException,
IllegalPropertyAccessException

Add another collection and it's array of item, optionally variable, and optionally event arrays to this collection as children of a new Folder child item of this collection.

Parameters:

newColl - The collection to combine with this one

copyScripts - Whether to copy the source collections events to the new parent folder

copyVariables - Whether to copy the source collections variables to the target collections array of variable elements. Note there is no checking for namespace collisions.

Throws:

RecursiveItemAddException - If the new collection is the same as this collection

InvalidCollectionActionException - If the specified parent is not a folder (e.g., contains a request element)

IllegalPropertyAccessException

addCollection

public void addCollection(Collection newColl,
 ItemGroup parent,
 boolean copyScripts,
 boolean copyVariables)
                   throws RecursiveItemAddException,
InvalidCollectionActionException,
IllegalPropertyAccessException

Add another collection and it's array of item, optionally variable, and optionally event arrays to this collection as children of the specified parent.

Parameters:

newColl - The collection to combine with this one

parent - The new parent object

copyScripts - Whether to copy the source collections events to the new parent folder

copyVariables - Whether to copy the source collections variables to the target collections array of variable elements. Note there is no checking for namespace collisions.

Throws:

RecursiveItemAddException - If the new collection is the same as this collection

InvalidCollectionActionException - If the specified parent is not a folder (e.g., contains a request element)

IllegalPropertyAccessException

addCollection

public void addCollection(Collection newColl)
                   throws RecursiveItemAddException,
InvalidCollectionActionException,
IllegalPropertyAccessException

Add another collection and it's array of item, variable, and event arrays to this collection in a new Folder. The new folder will have the same name as the collection added

Parameters:

newColl - The collection to add

Throws:

RecursiveItemAddException - If the new collection is the same as this collection

InvalidCollectionActionException

IllegalPropertyAccessException

setName

public void setName(String newName)

Overrides:

setName in class Item

Parameters:

newName -

setDescription

public void setDescription(String desc)

Description copied from class: Item

Set the value of the description property

Overrides:

setDescription in class Item

Parameters:

desc -

getDescription

public String getDescription()

Description copied from class: Item

Return the value of the description property

Overrides:

getDescription in class Item

Returns:

String

pmcFactory

public static Collection pmcFactory()

Static factory method to create the new collection. Default constructor is undefined to avoid conflict with Gson.

Returns:

Collection

pmcFactory

public static Collection pmcFactory(File jsonFile)
                             throws IOException

Static factory method to create a new Collection from a Postman collection JSON file.

Parameters:

jsonFile - The Postman Collection JSON file to ingest

Returns:

Collection The new collection

Throws:

FileNotFoundException - If the specified JSON file does not exist

IOException - If an IO exception occurs attempting to read the file, eg., inadequate permissions, etc.

pmcFactory

public static Collection pmcFactory(String json)

Parameters:

json -

Returns:

Collection

pmcFactory

public static Collection pmcFactory(URL collectionURL)
                             throws IOException,
InterruptedException,
IllegalArgumentException,
CollectionNotFoundException,
ValidationException,
InvalidCollectionActionException

Create a collection via the Postman API

Parameters:

collectionURL - URL for the collection to ingest

Returns:

Collection The new collection

Throws:

IOException

InterruptedException

IllegalArgumentException

CollectionNotFoundException - If there is no collection at the specified URL

ValidationException - If the JSON returned by the specified URL does not conform to the Postman schema

InvalidCollectionActionException - If any other error occurs during the generation of the collection asdfasdf

pmcFactory

public static Collection pmcFactory(PostmanID id)
                             throws IOException,
InterruptedException,
CollectionNotFoundException,
ValidationException,
InvalidCollectionActionException

Parameters:

id -

Returns:

Collection

Throws:

IOException

InterruptedException

CollectionNotFoundException

ValidationException

InvalidCollectionActionException

getName

public String getName()

Overrides:

getName in class Item

Returns:

String

setInfo

public void setInfo(HashMap<String,String> newInfo)

Set the value of this collections info object property with a populated Hash<String> containing the key-value pairs. Note that the keys are not validated.

Parameters:

newInfo -

getPostmanID

public String getPostmanID()

Return the _postman_id property of the info object property of this collection

Returns:

String The Postman ID

setPostmanID

public void setPostmanID(String id)

Set the _postman_id property of the info object property of this collection

Parameters:

id - The new ID

setExporterID

public void setExporterID(String id)

Set the _exporter_id property of the info object property of this collection

Parameters:

id -

setSchemaURI

public void setSchemaURI(URI schemaURI)

Set the schema property of the info object property of this collection

Parameters:

schemaURI -

setInfo

public void setInfo(String name,
 String description,
 String postmanID,
 String exporterID,
 String schemaURI)
             throws URISyntaxException

set all elements of the info property object of this collection. Values are not validated

Parameters:

name - The name property of the collection

description - The description property of the collection

postmanID - The _postman_id property of this collection

exporterID - The _exporter_id property of this colleciton

schemaURI - The URI for the schema of this collection

Throws:

URISyntaxException - If the provided string for schemaURI is not a properly constructed URI

writeToFile

public void writeToFile(File outputFile)
                 throws IOException

Write this collections generated JSON to a file at the specified path. Note that the order of elements in the resulting file is not guaranteed and may not match a corresponding Postman generated file. However, this does not affect the validity or functionality of the generated JSON.

Parameters:

outputFile - The file into which to write the JSON

Throws:

IOException - If there is an error attempting to create or write to the specified path

upsertToPostman

public PostmanID upsertToPostman()
                          throws IOException,
InterruptedException,
CollectionNotFoundException,
InvalidCollectionActionException

Throws:

IOException

InterruptedException

CollectionNotFoundException

InvalidCollectionActionException

upsertToPostman

public PostmanID upsertToPostman(PostmanID workspaceID)
                          throws IOException,
InterruptedException,
CollectionNotFoundException,
InvalidCollectionActionException

Create or update this collection in Postman. - If this collection has a Postman ID, it will be updated in Postman - If this collection does not have a Postman ID, it will be created as a new collection, and the ID returned by Postman will be assigned to it. - You can optionally include a workspace ID for a workspace to link a newly created collection to.

Parameters:

WorkspaceID - Optional workspace ID to which to link a newly created collection.

Throws:

IOException - If there is an error attempting to create or write to the specified path

InterruptedException - If the HTTP request is interrupted

CollectionNotFoundException - if the collection ID is not found in Postman

InvalidCollectionActionException - If an HTTP status code other than 200 or 404 is returned.

setAuth

public void setAuth(RequestAuth auth)

Set the auth object property of this collection with a RequestAuth object containing the values.

Parameters:

auth - The new auth values, or null to remove an existing auth.

getAuth

public RequestAuth getAuth()

Return the values in the auth object property of this collection, or null if it has not been set.

Returns:

RequestAuth The auth values, or null.

resolveVariables

public String resolveVariables(String src)
                        throws VariableResolutionException

Parameters:

src -

Returns:

String

Throws:

VariableResolutionException

toJson

public String toJson()

Generate JSON as text from the values in this collection.

Overrides:

toJson in class CollectionElement

Returns:

String

getInfo

public Map<String,String> getInfo()

Return a Map<String> containing the key-value pairs comprising the info object property of this collection.

Returns:

Map<String> The key-value pairs.

getKey

public String getKey()

Overrides:

getKey in class Item

Returns:

String

setVariables

public void setVariables(PropertyList<Property> vars)

Set the array of key-value pairs in this collections variable array element

Parameters:

vars - The ArrayList<Property> containing the variables

addVariable

public void addVariable(Property varNew)

Add or replace variable to the collection of variables comprising this collections variable array property. If a variable with the same key already exists in the collection it is replaced.

Parameters:

varNew -

removeVariable

public void removeVariable(String key)

Remove variable with the specified key from the array of key-value pairs comprising this collections variable array element.

Parameters:

key - Key of the variable to remove

removeVariable

public void removeVariable(Property varNew)

Remove variable from the array of key-value pairs comprising this collections variable array element.

Parameters:

varNew - The variable to remove. Matching is by the value of key

getVariable

public Property getVariable(String key)

Return the Property key-value pair from this collection's variable array element, or null if it is not present.

Parameters:

key -

Returns:

Property

getVariables

public PropertyList<Property> getVariables()

Get the ArrayList<Property> containing the key-value pairs comprising the variable array element of this collection

Returns:

ArrayList<Property>

addVariables

public void addVariables(PropertyList<Property> newVars)

Parameters:

newVars -