Portal Server 6.3

PAR Command

Par Command Location:

W2K: <home>\Sun\jstudio\PortalServer6.2\bin
Solaris: <installRoot>/SUNWps/bin

Working Examples:

par import -p <password> -r "uid=amadmin,ou=people,dc=<domainName>,dc=<domainRoot>" testChan.par global "channel"

This command imports the channel contained in the testChan.par file and loads it at the Global position. The JSP file is not included in the par file and must be manually moved to the appropriate directory.

Back to Menu



Excerpt From Documentation

Administering par Files

The par utility enables you to transfer or move providers or channels from one Sun Java System Portal Server to another. The par utility creates a specialized packaging mechanism called a .par file for transport of channels, portlets, and providers into and out of the server. A .par file is an extended form of the .jar file format, with added manifest information to carry the deployment information and an XML document intended for integration into the Sun Java System Portal Server display profile on the target server.

The par command line utility is used to create, modify, and deploy par files. The export subcommand allows you to create or modify a par file. The import subcommand allows you to import or deploy the provider, channel, or portlet on an Sun Java System Portal Server. The describe subcommand describes the contents of a par file. See par for detailed information on the syntax of the par command.

To use the par utility, you must be logged in as superuser to the Sun Java System Portal Server on which the files you want to export or import are resident. When you export you need to be sure to export all the required files for the channel, portlet, or provider. For example, with channels you must include the static content files and with providers you must include all the class files used by the provider. Because specifying all the data to be included in the par file on the command line can be cumbersome, a simple text file with lines indicating the data is created and this “export file” is called by the par utility. See Chapter 5, "Administering the Portal Desktop Service" for further information.

To Create a New par File

To create a new par file to export a channel, portlet, or provider:

  1. Log in to the Sun Java System Portal Server from which to export the channel, portlet, or provider.
  2. Change directories to the directory where the script is installed. That is:
  3. cd BaseDir/SUNWps/bin

  4. At the command line, enter the par export command and subcommand and include the following arguments: the name of the par file to create, a directory server name argument corresponding to the desired display profile document to export, and any number of (requires at least one) export files or from specifications. For example, to export the channel mychannel from o=sesta.com,o=isp to the mychannel.par file, enter
  5. ./par export mychannel.par "o=sesta.com,o=isp" from: channel mychannel

    See Appendix , "" for syntax information.

To Modify an Existing par File

To modify an existing par file to export a channel, portlet, or provider:

  1. Log in to the Sun Java System Portal Server from which to export the channel, portlet, or provider.
  2. Change directories to the directory where the script is installed. That is:
  3. cd BaseDir/SUNWps/bin

  4. At the command line, par export command and subcommand with the modify option and include the following arguments: the name of the par file to modify, a directory server name argument corresponding to the desired display profile document to export, and any number of (requires at least one) export tiles or from specifications. For example, to modify the mychannel.par file to include the static content file /mycontent.html, enter
  5. ./par export --modify mychannel.par "dc=sesta,dc=com" “from= file /mycontent.html”

To Deploy par Files

To import a par file to a Sun Java System Portal Server to deploy a provider or channel on the system:

  1. Copy the par file for the provider or channel to import to the Sun Java System Portal Server on which to deploy the provider or channel.
  2. Log in to the Sun Java System Portal Server on which to import the channel, portlet, or provider.
  3. Change directories to the directory where the script is installed. That is:
  4. cd BaseDir/SUNWps/bin

  5. At the command line, par import command and subcommand and include the following arguments: the name of the par file to import, a directory server name argument corresponding to the desired display profile document to export, For example, to import the mychannel.par file, enter
  6. ./par import --auto myfile.par "do=sesta,dc=com"


par

Description

The par command performs functions involving the specified .par file. It can be used for exporting and importing channels or providers to and from the Sun Java System Portal Server.

Syntax

The par command syntax is described in this section. Mixing long-named options with short ones in one command line is not recommended.

Short-Named Format

par containers -r uid -p password [-d] dn|global

par describe [-d] parfile

par export -r uid -p password [-m] [-d] -s staticdir [-v] parfile dn|global {exportfile|from=}...

par import -r uid -p password [-o] [-d] -s staticdir [-v] parfile [dn|global [op...]]

par import -r uid -p password  -a [-d] -s staticdir [-v] parfile [dn|global]

Long-Named Format

par containers --runasdn uid --password password [--debug] dn|global

par describe [--debug] parfile

par export --runasdn uid --password password [--modify] [--debug] --staticdir staticdir [--verbose] parfile dn|global {exportfile|from=}...

par import --runasdn uid --password password [--overwrite] [--debug] --staticdir staticdir [--verbose] parfile [dn|global [op...]]

par import --runasdn uid --password password --auto [--debug] --staticdir staticdir [--verbose] parfile [dn|global]

Subcommands

The following subcommands are supported:

containers

Description

Lists all available containers and channels in a particular display profile document, indicated by the specified directory server name (or global). This can be used as an aid to formulating other commands.

Syntax

par containers -r|--runasdn uid -p|--password password [-d|--debug] [-v|--verbose] dn|global

Example

par containers -r "uid=amAdmin,ou=people,o=sesta.com,o=isp" -p joshua -d "o=sesta.com,o=isp"

In this example, the command lists all available containers in the display profile document residing in the LDAP node "o=sesta.com,o=isp".

describe

Description

Describes the contents of the specified .par file, including the entries, and any built-in autoextract operations defined for the entries.

Syntax

par describe parfile

Example

par describe myfile.par

In this example, the command output or description of the myfile.par may be something like the following:


Class Root: /

Property Based File Root: /pbfiles

Display Profile Root: /dp

Static Content Root: /static

Entry: mychannel

AutoExtract:dpnode=o%3Dsesta.com%2Co%3Disp,channel,entry=mychannel

DP Document: this my JSP based channel.

Channel: SampleJSP.a

Includes: Property Based File, root templateBaseDir, path default/mychannel/samplecontent.jsp (channel)

Includes: Property Based File, root templateBaseDir, path default/mychannel/sampledoedit.jsp (channel)

Includes: Property Based File, root templateBaseDir, path default/mychannel/sampleedit.jsp (channel)

Includes: Property Based File, root templateBaseDir, path default_en_US/mychannel/samplecontent.jsp

(channel)

Includes: Property Based File, root templateBaseDir, path default_en_US/mychannel/sampledoedit.jsp

(channel)

Includes: Property Based File, root templateBaseDir, path default_en_US/mychannel/sampleedit.jsp

(channel)

export

Description

Populates the specified .par file by exporting the provider or channel information from the portal server. The command takes a .par file, a directory server name argument (or keyword global) corresponding to the desired display profile document to update, and any number of (requires at least one) exportfile or from specifications. The from specifications contain exactly the same information as an export file; the only difference is that the "lines" are separated by semicolons.

The par export command without the -m option creates a .par file. The par export command with the -m option is used to update and / or add to an already existing .par file that defines a provider, channel or container.

Syntax

par export -r|--runasdn uid -p|--password password [-d|--debug] -s|--staticdir staticdir [-v|--verbose] parfile dn|global {exportfile|from=}...

par export -r|--runasdn uid -p|--password password [-d|--debug] -s|--staticdir staticdir [-v|--verbose] -m|--modify parfile dn|global {exportfile|from=}...

Example

par export -r "uid=amAdmin,ou=people,dc=sesta,dc=com" -p joshua mychannel.par "o=sesta.com,o=isp" myexport.txt

Here myexport.txt contains:


from: channel mychannel

directory: templateBaseDir . mychannel

description: this is my JSP based channel

In this example, the command exports the channel definition and template files for mychannel into mychannel.par from the "dc=sesta,dc=isp" dn. Also, if it were a JSPProvider channel, the directory line transfers all of the .jsp files, including locale-specific versions.

import

Description

Imports objects from the specified .par file into the portal server. The command takes a .par file, and optional arguments for the display profile document to import the objects into the indicated display node in the directory server (or the root display profile indicated by the keyword global), and operations to be performed. If these things are not specified, they are taken from the .par file. The auto option can be used to indicate that you wish to simply perform the autoextract operations already contained in the .par file.

If you want to add a new channel, you can use the par import command with or without the -o option. If a channel already exists, you must use the -o option with the par import command to completely replace (overwrite) the old channel. You can use this subcommand to import providers as well as channels.

Syntax

par import -r|--runasdn uid -p|--password password [-o] [-d|--debug] -s|--staticdir staticdir [-v|--verbose] parfile [dn|global [op...]]

par import -r|--runasdn uid -p|--password password -a|--auto [-d|--debug] -s|--staticdir staticdir [-v|--verbose] parfile [dn|global]

Examples
Example 1

par import -r "uid=amAdmin,ou=people,o=sesta.com,o=isp" -p joshua --auto myfile.par "o=sesta.com,o=isp"

In this example, the command extracts the channel from myfile.par file, if that is the automatic operation defined in the myfile.par parfile.

Example 2

par import -r "uid=amAdmin,ou=people,o=sesta.com,o=isp" -p joshua myfile.par "o=sesta.com,o=isp" "entry=mychannel,channel=anothername,avail=topcontainer"

In this example, the command extracts the channel explicitly, installing it with a different name in the target dn, and making it available in container topcontainer.

Options

Table 21-13 contains two columns: the first column lists the possible options for the par command; the second column gives a brief description. This command supports the following options (listed in alphabetical order):

Table 21-13  par Command Options

Options

Description

 

 

-a or --auto

Use with the import command to apply the autoextract operations from the .par file. There should be no operations specified on the command line in this case. The dn argument may still be specified; if specified, it replaces the dn in the autoextract operations. If operations are specified on the command line they are ignored.

-d or --debug

Specify this to produce extra debugging information on error messages.

-m or --modify

Use with the export command to update an existing .par file rather than replace it. Any new files added for an entry supplement or replace the old ones. Also, use this command to add new files to an existing provider or channel by using a .par file.

-o or --overwrite

Use with the import command to replace existing channels.

-p or --password

Specifies the password for authentication. Required for all of the subcommands except describe. If not specified, the par utility prompts for it.

-r or --runasdn

Specifies the distinguished name of the user for authentication. Required for all of the commands except describe. If not provided, the par utility prompts for it. Use the format uid=userName,ou=people,o=organizationName,o=organizationalUnit

-s or --staticdir

Defines the host-specific directory of the static content directory to be used for import or export.

-v or --verbose

Describes operations as they are executed. Use with the import and export commands.

-V or --version

Specify this option to par to print descriptive information about the utility, such as its version, legal notices, and other similar information to standard output. Any subcommand and all other options are ignored when this option is present.

-?

Obtain help for any subcommand.

Arguments

Table 21-14 contains two columns: the first column lists the possible arguments for the par command; the second column gives a brief description. This command takes the following arguments:

Table 21-14  par Command Arguments

Argument

Description

dn

Specifies the distinguished node in the directory server to access. Use the format "o=organizationName,o=organizationalUnit"

global

Specifies the global level node in LDAP to access the display profile document.

exportfile

These files each correspond to an entry (provider, channel, or provider/channel combination) in the .par file, and simply specify the data to be inserted into the specified .par file. It can be a small file if the information is too large to list on the command line. See Export Files for more information.

from

Specified on the command line, this is taken as equivalent to an export file containing the "from" line, followed by an equal to ("=") sign, and any other lines separated by a semicolon (";"). See from in Table 21-15 for more information on line properties.

op

Specifies the operation to perform. See Operations for more detail.

parfile

Specifies the par file to operate upon; that is, indicates the par file to import, export, or describe.

Export Files

These files simply specify data to be inserted into a .par file. The file consists of lines containing a keyword, followed by a colon and white space delimited fields. The line "from:" is required and it must be the first line of the file. Lines beginning with "#" are treated as comments.

Table 21-15 contains two columns: the first column lists the possible line keywords; the second column gives a brief description.

Table 21-15  Export File Line Properties

Line

Description

from: types name

“from” indicates what entity is being exported. types can be “channel”, “provider”, or “channel,provider”, and “channel+provider”. The name indicates the channel name, or a provider name if a provider is being exported. The name must be URL encoded if the name contains white space (+), commas (%2C), colons (%3A), semicolons (%3B), plus signs (%2B), or percent signs (%25).

auto: none

"auto" specifies the autoextract operation for the entry. It takes the op argument followed by the operation. "none" can also be entered, suppressing the autoextract. If no "auto:" line is specified, a default autoextract is produced. The default operation is to extract the channel and/or provider with its original names.

auto: op

file: root|. path [types]

"file" indicates that a file, based on a property setting, is to be included. The property can come from either the "desktop properties" file, located by default in /etc/opt/SUNWps/desktop/desktopconfig.properties file or from the display profile visible to a getProperty() call for the item being exported or imported. root specifies the root of the file location and path specifies the path to the rest of the file. root is a property name that corresponds to a directory (like). If root is given as ".", the file is assumed to be static content located at the web server’s doc root. You can also specify the types of operation the file is to be associated with, defaulting to "channel". types can be “channel”, “provider”, or “channel,provider”, and “channel+provider”.

class: class [types]

"class" indicates that a class file is to be packaged with the entry, and you may optionally specify the types of operations that the class file are associated with. If not specified, "provider" is assumed. types can be "channel", "provider", or "channel,provider", and "channel+provider"; also, when specifying both, you can use a space.

directory: root|. dir +|.|filter [types]

"directory" implies an entire directory search with all non-directory files to be included as if entered as "file" lines. It includes the capability of specifying a "filter", that is a directory component which must be present in recursive directory searches. root specifies the root of the directory, or "." to indicate static content. dir is the directory underneath the root to search from, which can be given as "." to start at the root itself. filter specifies the filter component which must be in the directory, which implies a recursive descent. It can be given as "+" for a recursive descent with no filter, or "." for no recursive descent (just the contents of the actual directory). You can also specify the types of operation, which default to "channel". types can be “channel”, “provider”, or “channel,provider”, and “channel+provider”.

entry: name

"entry" specifies the entry name used in the .par file. If not specified, it defaults to the name from the "from: " line.

desc: text

Any number of "desc" lines may appear, and are concatenated together as a user-visible description packaged with the entry.

Operations

Each operation (op), in the export file or on the command line, must be specified as a comma separated list of keywords that can have values, most of which are optional. The operations are in a blank or space separated list. Each operation is in the following format.

dpnode=dn,entry=name,provider[=name],channel[=name],container=name[,avail=nam e,selected]

dpnode

This specifies the distinguished name in the directory server (or the keyword global) for the display profile document that this operation is targeted at. May not apply if the context it is being specified in has already provided this. For example, if the import subcommand defines the distinguished name, the distinguished name in the file is ignored.

entry

This specifies the entry name in the .par file. This is not needed if the:

The par utility defaults to the first entry in the file if an entry is not specified.

provider

This indicates that a provider extraction is to take place. If the name is missing, it simply uses the name packaged with the provider in the .par file.

channel

This indicates that a channel extraction is to take place. If the name is missing, it simply uses the name provided with the channel in the .par file.

container

This applies only to channel extractions and indicates which container the channel is to be inserted into. If omitted, the channel is inserted into the "channels" element at the display profile document root.

avail

This applies only to channel extractions and indicates a container whose "avail" (or available) list is to receive a reference to the new channel. If omitted, no new channel reference is created.

selected

This applies only if "avail" was used. It indicates that the container whose "avail" list received a reference, also has a reference placed in its "selected" list.

If the op information is in both the par import command and in the .par file, the command information takes precedence.

Par Files

This section contains supplemental information on the par file format. You do not require this information to run the par command.

The par file is a jar file with manifest entries for transporting channels, providers, and their associated files. It is intended allow flexibly when installing providers, channels, or both. The .par file contains 4 major types of files:

  1. XML documents containing the provider and/or channel information for the display profile. This document is a "parEntry", as described in the display profile dtd. This parEntry contains a channel, a provider, or a channel/provider combination.
  2. Class files associated with the provider and/or channel.
  3. Property based files. These are general files associated with the channel, portlet, or provider (usually the channel), which have to be deployed underneath some configurable root on the portal server.
  4. Static content files. These are files deployed as documents on the web server.

Par File Contents

Table 21-16 contains two columns: the first column lists the required global headers; the second column gives a brief description. The .par file must contain the following headers:

Table 21-16  Global Headers

Header

Description

PS-Version

Specifies a portal server specific version number of the .par file. Also verifies that this is a .par file.

PS-DefaultEntry

Names the entry used for operations involving an unnamed entry.

PS-DPRoot

Indicates the root directories in the archive for parEntry documents, classes, property based files, and static content, respectively. If unspecified, the corresponding files are rooted at the top of the archive.

 

PS-ClassRoot

PS-PBFileRoot

PS-StaticRoot

In the .par file, there must be a named entry for each parEntry XML file. Table 21-17 contains two columns: the first column lists the possible headers; the second column gives a brief description. The section for each named entry may contain the following headers:

Table 21-17  Named Entry Headers

Header

Description

PS-EntryName

Specifies the command visible name of the entry.

PS-AutoExtract

Specifies the autoextract operation for the entry, if one exists.

PS-Include

Contains a comma separated list of archived files specified by their actual archive path. The path implies what type of file they are according to the "root" specifications. The files are appended with a parenthesized number which corresponds to the types of operations the file applies to (a mask with 1 for provider, 2 for channel). This can be ignored if there are no files other than the XML document associated with the entry.

If the .par file contains only one entry, entries need not be named in manipulating the file since the default entry is the entry used if none is named.


Back to Menu